Fitur lanjutan MSE Ingress - Microservices Engine - Alibaba Cloud Documentation Center

MSE Ingress adalah objek API Kubernetes yang menyediakan penyeimbangan beban Layer-7 untuk mengontrol akses eksternal ke layanan dalam kluster. Topik ini mencakup konfigurasi lanjutan berbasis anotasi untuk tata kelola lalu lintas, termasuk rilis canary, CORS, penulisan ulang path dan host, pengalihan, kontrol header, retry, kontrol akses berbasis IP, pembatasan laju, pencerminan lalu lintas, penyeimbangan beban, persistensi sesi, kolam koneksi, dan pengaturan TLS.

Rilis canary

MSE Ingress mendukung empat metode rilis canary: berbasis header, berbasis parameter kueri, berbasis cookie, dan berbasis bobot. Konfigurasikan rilis canary dengan menambahkan anotasi ke sumber daya Ingress. Semua sumber daya Ingress canary memerlukan anotasi nginx.ingress.kubernetes.io/canary: "true".

Ketika beberapa metode dikonfigurasi secara bersamaan, MSE Ingress menerapkannya dalam urutan prioritas berikut:

Header-based or query parameter-based > Cookie-based > Weight-based

MSE Ingress mendukung jumlah versi canary tak terbatas per entri rute. NGINX Ingress dan ALB Ingress mendukung maksimal dua versi.

Rilis canary berbasis header

Gunakan anotasi berikut untuk mengarahkan lalu lintas berdasarkan header permintaan:

Anotasi	Perilaku
`nginx.ingress.kubernetes.io/canary-by-header`	Mengarahkan ke versi canary ketika nilai header adalah `always`. Semua nilai lainnya mengarah ke versi dasar.
`nginx.ingress.kubernetes.io/canary-by-header-value`	Digunakan bersama dengan `canary-by-header`. Mengarahkan ke versi canary hanya ketika kunci dan nilai header cocok secara tepat.

Contoh 1: Arahkan ke satu versi canary berdasarkan header

Permintaan dengan header mse: always menuju demo-service-canary. Semua permintaan lainnya menuju demo-service.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "mse"
  name: demo-canary
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /hello
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "mse"
  name: demo-canary
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service-canary
              servicePort: 80
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Contoh 2: Arahkan ke beberapa versi canary berdasarkan nilai header

Permintaan dengan mse: v1 menuju demo-service-canary-v1. Permintaan dengan mse: v2 menuju demo-service-canary-v2. Semua permintaan lainnya menuju demo-service.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "mse"
    nginx.ingress.kubernetes.io/canary-by-header-value: "v1"
  name: demo-canary-v1
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary-v1
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "mse"
    nginx.ingress.kubernetes.io/canary-by-header-value: "v2"
  name: demo-canary-v2
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary-v2
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /hello
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "mse"
    nginx.ingress.kubernetes.io/canary-by-header-value: "v1"
  name: demo-canary-v1
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service-canary-v1
              servicePort: 80
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "mse"
    nginx.ingress.kubernetes.io/canary-by-header-value: "v2"
  name: demo-canary-v2
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service-canary-v2
              servicePort: 80
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Rilis canary berbasis parameter kueri

Gunakan anotasi berikut untuk mengarahkan lalu lintas berdasarkan parameter kueri URL:

Anotasi	Perilaku
`mse.ingress.kubernetes.io/canary-by-query`	Mengarahkan ke versi canary ketika kunci parameter kueri cocok dan nilainya adalah `always`.
`mse.ingress.kubernetes.io/canary-by-query-value`	Digunakan bersama dengan `canary-by-query`. Mengarahkan ke versi canary hanya ketika kunci dan nilai kueri cocok secara tepat.

Metode berbasis header dan parameter kueri dapat digabungkan. Permintaan diarahkan ke versi canary hanya jika kedua kondisi pencocokan terpenuhi.

Contoh 1: Arahkan hanya berdasarkan parameter kueri

Permintaan dengan parameter kueri canary=gray menuju demo-service-canary. Semua permintaan lainnya menuju demo-service.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    mse.ingress.kubernetes.io/canary-by-query: "canary"
    mse.ingress.kubernetes.io/canary-by-query-value: "gray"
  name: demo-canary
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /hello
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    mse.ingress.kubernetes.io/canary-by-query: "canary"
    mse.ingress.kubernetes.io/canary-by-query-value: "gray"
  name: demo-canary
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service-canary
              servicePort: 80
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Contoh 2: Gabungkan pencocokan parameter kueri dan header

Permintaan dengan canary=gray di URL dan x-user-id: test di header menuju demo-service-canary. Semua permintaan lainnya menuju demo-service.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    mse.ingress.kubernetes.io/canary-by-query: "canary"
    mse.ingress.kubernetes.io/canary-by-query-value: "gray"
    nginx.ingress.kubernetes.io/canary-by-header: "x-user-id"
    nginx.ingress.kubernetes.io/canary-by-header-value: "test"
  name: demo-canary
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /hello
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  anotasi:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "x-user-id"
    nginx.ingress.kubernetes.io/canary-by-header-value: "test"
    # Mengarahkan ke Pod dengan Label version: gray
    mse.ingress.kubernetes.io/service-subset: gray
    mse.ingress.kubernetes.io/subset-labels: version gray
  name: demo-canary
  namespace: default
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /test
            backend:
              serviceName: go-httpbin
              servicePort: 8080
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  anotasi:
    mse.ingress.kubernetes.io/service-subset: ""
  name: demo
  namespace: default
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /test
            backend:
              serviceName: go-httpbin
              servicePort: 8080

</details>

Rilis canary berbasis cookie

Gunakan nginx.ingress.kubernetes.io/canary-by-cookie untuk mengarahkan lalu lintas berdasarkan cookie. Permintaan dikirim ke versi canary ketika nilai cookie adalah always.

Nilai cookie kustom tidak didukung. Nilai cookie harus always.

Example: Permintaan dengan cookie demo=always menuju demo-service-canary. Semua permintaan lainnya menuju demo-service.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-cookie: "demo"
  name: demo-canary
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /hello
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-cookie: "demo"
  name: demo-canary
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service-canary
              servicePort: 80
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Rilis canary berbasis bobot

Anotasi	Deskripsi	Bawaan
`nginx.ingress.kubernetes.io/canary-weight`	Persentase permintaan yang diarahkan ke versi canary. Bilangan bulat dari 0 hingga 100.	—
`nginx.ingress.kubernetes.io/canary-weight-total`	Bobot total yang digunakan sebagai penyebut untuk perhitungan bobot.	`100`

Proporsi lalu lintas yang dikirim ke versi canary adalah canary-weight / canary-weight-total. Saat menggunakan beberapa versi canary, atur bobot agar jumlahnya kurang dari canary-weight-total; proporsi sisanya menuju versi dasar.

Example: Bagi lalu lintas ke tiga versi — 30% ke demo-service-canary-v1, 20% ke demo-service-canary-v2, dan 50% ke demo-service.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "30"
  name: demo-canary-v1
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary-v1
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"
  name: demo-canary-v2
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary-v2
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /hello
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "30"
  name: demo-canary-v1
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service-canary-v1
              servicePort: 80
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"
  name: demo-canary-v2
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service-canary-v2
              servicePort: 80
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Subset layanan

Subset layanan mengarahkan permintaan ke kelompok Pod tertentu dalam suatu layanan — misalnya, ketika satu Service Kubernetes didukung oleh beberapa Deployment yang menjalankan versi berbeda. Gunakan salah satu metode berikut untuk mengonfigurasi subset layanan.

Gunakan label Pod di MseIngressConfig

Gunakan mse.ingress.kubernetes.io/service-subset untuk mengarahkan ke Pod dengan awalan label opensergo.io/canary tertentu.

"" atau base: mengarahkan ke Pod yang labelnya tidak mengandung awalan opensergo.io/canary, atau nilai labelnya kosong.
Nilai lain (misalnya, gray): mengarahkan ke Pod dengan label opensergo.io/canary-{value}: {value} (misalnya, opensergo.io/canary-gray: gray).

Example: Sebuah Service bernama go-httpbin didukung oleh dua Deployment — satu Deployment dasar (tanpa label opensergo.io/canary) dan satu Deployment gray (label opensergo.io/canary-gray: gray). Permintaan dengan header x-user-id: test menuju Deployment gray. Semua permintaan lainnya menuju Deployment dasar.

# Service Kubernetes go-httpbin
apiVersion: v1
kind: Service
metadata:
  name: go-httpbin
  namespace: default
spec:
  ports:
    - port: 8080
      protocol: TCP
  selector:
    app: go-httpbin
---
# Deployment Dasar
apiVersion: apps/v1
kind: Deployment
metadata:
  name: go-httpbin-base
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: go-httpbin
  template:
    metadata:
      labels:
        app: go-httpbin
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/mse/go-httpbin
          args:
            - "--version=base"
          imagePullPolicy: Always
          name: go-httpbin
---
# Deployment Gray
apiVersion: apps/v1
kind: Deployment
metadata:
  name: go-httpbin-gray
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: go-httpbin
  template:
    metadata:
      labels:
        app: go-httpbin
        opensergo.io/canary-gray: gray
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/mse/go-httpbin
          args:
            - "--version=gray"
          imagePullPolicy: Always
          name: go-httpbin

# Ingress — Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "x-user-id"
    nginx.ingress.kubernetes.io/canary-by-header-value: "test"
    # Arahkan ke Pod dengan label opensergo.io/canary-gray: gray
    mse.ingress.kubernetes.io/service-subset: gray
  name: demo-canary
  namespace: default
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: go-httpbin
                port:
                  number: 8080
            path: /test
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    # Arahkan ke Pod tanpa awalan label opensergo.io/canary
    mse.ingress.kubernetes.io/service-subset: ""
  name: demo
  namespace: default
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: go-httpbin
                port:
                  number: 8080
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "x-user-id"
    nginx.ingress.kubernetes.io/canary-by-header-value: "test"
    # Arahkan ke Pod dengan label opensergo.io/canary-gray: gray
    mse.ingress.kubernetes.io/service-subset: gray
  name: demo-canary
  namespace: default
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /test
            backend:
              serviceName: go-httpbin
              servicePort: 8080
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    # Arahkan ke Pod tanpa awalan label opensergo.io/canary
    mse.ingress.kubernetes.io/service-subset: ""
  name: demo
  namespace: default
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /test
            backend:
              serviceName: go-httpbin
              servicePort: 8080

</details>

Gunakan label kustom

Gunakan mse.ingress.kubernetes.io/service-subset dan mse.ingress.kubernetes.io/subset-labels untuk menentukan label kustom guna pemilihan subset Pod. Ketika subset-labels dikonfigurasi, subset tidak lagi dipetakan ke awalan label opensergo.io/canary.

Ketika mse.ingress.kubernetes.io/subset-labels diatur, pemetaan awalan opensergo.io/canary dinonaktifkan.

Example: Skenario yang sama seperti di atas, tetapi Pod gray diidentifikasi oleh label kustom version: gray alih-alih label opensergo.io/canary-gray.

# Service Kubernetes go-httpbin
apiVersion: v1
kind: Service
metadata:
  name: go-httpbin
  namespace: default
spec:
  ports:
    - port: 8080
      protocol: TCP
  selector:
    app: go-httpbin
---
# Deployment Dasar
apiVersion: apps/v1
kind: Deployment
metadata:
  name: go-httpbin-base
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: go-httpbin
  template:
    metadata:
      labels:
        app: go-httpbin
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/mse/go-httpbin
          args:
            - "--version=base"
          imagePullPolicy: Always
          name: go-httpbin
---
# Deployment Gray (label kustom)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: go-httpbin-gray
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: go-httpbin
  template:
    metadata:
      labels:
        app: go-httpbin
        version: gray
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/mse/go-httpbin
          args:
            - "--version=gray"
          imagePullPolicy: Always
          name: go-httpbin

# Ingress — Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "x-user-id"
    nginx.ingress.kubernetes.io/canary-by-header-value: "test"
    # Arahkan ke Pod dengan label version: gray
    mse.ingress.kubernetes.io/service-subset: gray
    mse.ingress.kubernetes.io/subset-labels: version gray
  name: demo-canary
  namespace: default
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: go-httpbin
                port:
                  number: 8080
            path: /test
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/service-subset: ""
  name: demo
  namespace: default
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: go-httpbin
                port:
                  number: 8080
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "x-user-id"
    nginx.ingress.kubernetes.io/canary-by-header-value: "test"
    # Arahkan ke Pod dengan label version: gray
    mse.ingress.kubernetes.io/service-subset: gray
    mse.ingress.kubernetes.io/subset-labels: version gray
  name: demo-canary
  namespace: default
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /test
            backend:
              serviceName: go-httpbin
              servicePort: 8080
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/service-subset: ""
  name: demo
  namespace: default
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /test
            backend:
              serviceName: go-httpbin
              servicePort: 8080

</details>

CORS

Cross-origin resource sharing (CORS) mengontrol origin, metode, dan header mana yang diizinkan dalam permintaan lintas asal. Untuk informasi lebih lanjut, lihat Cross-Origin Resource Sharing (CORS).

Anotasi	Deskripsi	Bawaan
`nginx.ingress.kubernetes.io/enable-cors`	Mengaktifkan CORS.	—
`nginx.ingress.kubernetes.io/cors-allow-origin`	Origin yang diizinkan. Dipisahkan koma. Wildcard (`*`) didukung.	`*`
`nginx.ingress.kubernetes.io/cors-allow-methods`	Metode permintaan yang diizinkan. Dipisahkan koma. Wildcard (`*`) didukung.	`GET,PUT,POST,DELETE,PATCH,OPTIONS`
`nginx.ingress.kubernetes.io/cors-allow-headers`	Header permintaan yang diizinkan. Dipisahkan koma. Wildcard (`*`) didukung.	`DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization`
`nginx.ingress.kubernetes.io/cors-expose-headers`	Header respons yang diekspos ke browser. Dipisahkan koma.	—
`nginx.ingress.kubernetes.io/cors-allow-credentials`	Mengizinkan kredensial dalam permintaan CORS.	`true`
`nginx.ingress.kubernetes.io/cors-max-age`	Durasi cache maksimum untuk hasil preflight, dalam detik.	`1728000`

Example: Izinkan example.com sebagai origin, izinkan hanya metode GET dan POST, batasi header yang diizinkan ke X-Foo-Bar, dan larang kredensial.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/cors-allow-origin: "example.com"
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET,POST"
    nginx.ingress.kubernetes.io/cors-allow-headers: "X-Foo-Bar"
    nginx.ingress.kubernetes.io/cors-allow-credentials: "false"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /hello
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/cors-allow-origin: "example.com"
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET,POST"
    nginx.ingress.kubernetes.io/cors-allow-headers: "X-Foo-Bar"
    nginx.ingress.kubernetes.io/cors-allow-credentials: "false"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Pencocokan ekspresi reguler

Selain tipe path Exact dan Prefix yang didukung oleh Ingress Kubernetes standar, MSE Ingress mendukung pencocokan ekspresi reguler. Tambahkan nginx.ingress.kubernetes.io/use-regex: "true" untuk memperlakukan nilai path sebagai ekspresi reguler.

Example: Arahkan permintaan ke example.com di mana path dimulai dengan /app atau /test ke layanan demo.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/use-regex: 'true'
  name: regex-match
  namespace: default
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo
                port:
                  number: 8080
            path: /(app|test)/(.*)
            pathType: Prefix

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/use-regex: 'true'
  name: regex-match
  namespace: default
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /(app|test)/(.*)
            backend:
              serviceName: demo
              servicePort: 8080

</details>

Penulisan ulang path dan host

Tulis ulang path atau host permintaan sebelum MSE Ingress meneruskan lalu lintas ke layanan backend.

Anotasi	Deskripsi
`nginx.ingress.kubernetes.io/rewrite-target`	Path tujuan untuk penulisan ulang. Grup tangkapan didukung.
`nginx.ingress.kubernetes.io/upstream-vhost`	Host tujuan untuk penulisan ulang.

Penulisan ulang path

Contoh 1: Tulis ulang path tetap

Tulis ulang example.com/test menjadi example.com/dev sebelum diteruskan ke backend.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: "/dev"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: "/dev"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /test
            pathType: Exact
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Contoh 2: Hapus awalan path

Hapus awalan /v1 sehingga example.com/v1/xxx menjadi example.com/xxx sebelum diteruskan ke backend.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: "/$1"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /v1/(.*)
            pathType: Prefix

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: "/$1"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /v1/(.*)
            pathType: Prefix
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Contoh 3: Ganti awalan path

Ubah awalan /v1 menjadi /v2 sehingga example.com/v1/xxx menjadi example.com/v2/xxx.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: "/v2/$1"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /v1/(.*)
            pathType: Prefix

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: "/v2/$1"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /v1/(.*)
            pathType: Prefix
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Penulisan ulang host

Example: Tulis ulang host dari example.com menjadi test.com sebelum meneruskan example.com/test ke backend.

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

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/upstream-vhost: "test.com"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Pengalihan

Pengalihan HTTP ke HTTPS

Anotasi	Deskripsi
`nginx.ingress.kubernetes.io/ssl-redirect`	Mengalihkan permintaan HTTP ke HTTPS.
`nginx.ingress.kubernetes.io/force-ssl-redirect`	Mengalihkan permintaan HTTP ke HTTPS.

MSE Ingress memperlakukan kedua anotasi secara identik — keduanya mengalihkan HTTP ke HTTPS secara paksa.

Example: Alihkan http://example.com/test ke https://example.com/test.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Pengalihan permanen

Anotasi	Deskripsi	Bawaan
`nginx.ingress.kubernetes.io/permanent-redirect`	URL tujuan untuk pengalihan permanen. Harus menyertakan skema (`http://` atau `https://`).	—
`nginx.ingress.kubernetes.io/permanent-redirect-code`	Kode status HTTP untuk pengalihan permanen.	`301`

Example: Alihkan secara permanen http://example.com/test ke http://example.com/app.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/permanent-redirect: "http://example.com/app"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/permanent-redirect: "http://example.com/app"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Pengalihan sementara

Gunakan nginx.ingress.kubernetes.io/temporal-redirect untuk menentukan URL tujuan pengalihan sementara. URL harus menyertakan skema (http:// atau https://).

Example: Alihkan sementara http://example.com/test ke http://example.com/app.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/temporal-redirect: "http://example.com/app"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/temporal-redirect: "http://example.com/app"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Kontrol header

MSE Ingress memungkinkan Anda menambah, memperbarui, atau menghapus header permintaan dan respons sebelum lalu lintas diteruskan.

Kontrol header permintaan

Anotasi	Deskripsi
`mse.ingress.kubernetes.io/request-header-control-add`	Menambahkan header ke permintaan yang diteruskan. Jika header sudah ada, nilai baru ditambahkan ke nilai yang ada. Header tunggal: pasangan kunci-nilai. Beberapa header: gunakan skalar blok YAML (`\|`), satu pasangan per baris.
`mse.ingress.kubernetes.io/request-header-control-update`	Memodifikasi header dalam permintaan yang diteruskan. Jika header sudah ada, nilai baru menggantikan nilai yang ada. Header tunggal: pasangan kunci-nilai. Beberapa header: gunakan skalar blok YAML (`\|`), satu pasangan per baris.
`mse.ingress.kubernetes.io/request-header-control-remove`	Menghapus header dari permintaan yang diteruskan. Header tunggal: hanya kunci. Beberapa header: dipisahkan koma.

Contoh 1: Tambahkan beberapa header permintaan

Tambahkan foo: bar dan test: true ke permintaan ke example.com/test.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/request-header-control-add: |
      foo bar
      test true
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/request-header-control-add: |
      foo bar
      test true
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Contoh 2: Gabungkan kontrol header dengan rilis canary

Beri tag permintaan dengan header stage untuk mengidentifikasi versi mana yang menanganinya. Permintaan dengan mse: v1 menuju demo-service-canary-v1 dan menerima stage: gray. Semua permintaan lainnya menuju demo-service dan menerima stage: production.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "mse"
    nginx.ingress.kubernetes.io/canary-by-header-value: "v1"
    mse.ingress.kubernetes.io/request-header-control-add: "stage gray"
  name: demo-canary-v1
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service-canary-v1
                port:
                  number: 80
            path: /hello
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/request-header-control-add: "stage production"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /hello
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "mse"
    nginx.ingress.kubernetes.io/canary-by-header-value: "v1"
    mse.ingress.kubernetes.io/request-header-control-add: "stage gray"
  name: demo-canary-v1
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service-canary-v1
              servicePort: 80
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/request-header-control-add: "stage production"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Kontrol header respons

Anotasi	Deskripsi
`mse.ingress.kubernetes.io/response-header-control-add`	Menambahkan header ke respons sebelum diteruskan ke klien. Jika header ada, nilai ditambahkan.
`mse.ingress.kubernetes.io/response-header-control-update`	Memodifikasi header dalam respons sebelum diteruskan ke klien. Jika header ada, nilai diganti.
`mse.ingress.kubernetes.io/response-header-control-remove`	Menghapus header dari respons sebelum diteruskan ke klien. Header tunggal: hanya kunci. Beberapa header: dipisahkan koma.

Example: Hapus header req-cost-time dari respons ke example.com/test.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/response-header-control-remove: "req-cost-time"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/response-header-control-remove: "req-cost-time"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Retry

MSE Ingress mendukung retry otomatis tingkat entri rute pada permintaan yang gagal. Konfigurasikan kondisi yang memicu retry, batas retry, dan timeout per retry.

Anotasi	Deskripsi	Bawaan
`nginx.ingress.kubernetes.io/proxy-next-upstream-tries`	Jumlah maksimum upaya retry.	`3`
`nginx.ingress.kubernetes.io/proxy-next-upstream-timeout`	Timeout untuk setiap upaya retry, dalam detik. Ini adalah timeout per upaya, bukan anggaran total untuk semua retry.	Tanpa timeout
`nginx.ingress.kubernetes.io/proxy-next-upstream`	Kondisi retry. Dipisahkan koma.	`error,timeout`

Penting

proxy-next-upstream-timeout berlaku untuk setiap upaya retry secara independen. Jika Anda mengatur 3 retry dengan timeout 5 detik, waktu retry maksimum total adalah 15 detik, bukan 5 detik.

Kondisi retry yang valid untuk proxy-next-upstream:

Nilai	Memicu retry saat...
`error`	Koneksi gagal atau status 5xx dikembalikan.
`timeout`	Koneksi timeout atau status 5xx dikembalikan.
`invalid_header`	Permintaan tidak valid dan status 5xx dikembalikan.
`http_xxx`	Kode status yang ditentukan dikembalikan (misalnya, `http_502`, `http_403`).
`non_idempotent`	Permintaan non-idempoten (POST, PATCH) gagal. Secara bawaan, MSE Ingress tidak melakukan retry permintaan non-idempoten.
`off`	Retry dinonaktifkan.

Example: Untuk example.com/test, atur maksimal 2 retry, timeout 5 detik per retry, picu retry hanya pada respons 502, dan izinkan retry untuk permintaan non-idempoten.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-next-upstream-tries: "2"
    nginx.ingress.kubernetes.io/proxy-next-upstream-timeout: "5"
    nginx.ingress.kubernetes.io/proxy-next-upstream: "http_502,non_idempotent"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-next-upstream-tries: "2"
    nginx.ingress.kubernetes.io/proxy-next-upstream-timeout: "5"
    nginx.ingress.kubernetes.io/proxy-next-upstream: "http_502,non_idempotent"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Kontrol akses berbasis IP

MSE Ingress mendukung kontrol akses berbasis IP baik di tingkat entri rute maupun tingkat nama domain. Aturan tingkat entri rute memiliki prioritas lebih tinggi daripada aturan tingkat domain.

Kontrol akses IP tingkat entri rute

Anotasi	Deskripsi
`nginx.ingress.kubernetes.io/whitelist-source-range`	Daftar putih alamat IP untuk entri rute. Menerima alamat IP dan Blok CIDR, dipisahkan koma.
`mse.ingress.kubernetes.io/blacklist-source-range`	Daftar hitam alamat IP untuk entri rute. Menerima alamat IP dan Blok CIDR, dipisahkan koma.

Contoh 1: Mengizinkan alamat IP tertentu untuk mengakses entri rute

Izinkan akses ke example.com/test hanya dari 1.1.X.X.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/whitelist-source-range: 1.1.X.X
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/whitelist-source-range: 1.1.X.X
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Contoh 2: Blokir IP tertentu dari mengakses entri rute

Tolak akses ke example.com/test dari 2.2.2.2.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/blacklist-source-range: 2.2.2.2
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/blacklist-source-range: 2.2.2.2
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Kontrol akses IP tingkat domain

Anotasi	Deskripsi
`mse.ingress.kubernetes.io/domain-whitelist-source-range`	Daftar putih alamat IP untuk semua entri rute di bawah domain. Daftar putih tingkat entri rute memiliki prioritas. Menerima alamat IP dan Blok CIDR, dipisahkan koma.
`mse.ingress.kubernetes.io/domain-blacklist-source-range`	Daftar hitam alamat IP untuk semua entri rute di bawah domain. Daftar hitam tingkat entri rute memiliki prioritas. Menerima alamat IP dan Blok CIDR, dipisahkan koma.

Contoh 1: Izinkan IP tertentu mengakses semua entri rute di bawah domain

Izinkan akses ke semua entri rute example.com dari 1.1.X.X dan 2.2.2.2.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/domain-whitelist-source-range: 1.1.X.X,2.2.2.2
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact
          - backend:
              service:
                name: app-service
                port:
                  number: 80
            path: /app
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/domain-whitelist-source-range: 1.1.X.X,2.2.2.2
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80
          - path: /app
            backend:
              serviceName: app-service
              servicePort: 80

</details>

Contoh 2: Gabungkan kontrol akses tingkat domain dan tingkat entri rute

Izinkan 1.1.X.X dan 2.2.2.2 mengakses semua entri rute di bawah example.com, tetapi batasi example.com/order hanya untuk 3.3.X.X (tingkat entri rute memiliki prioritas).

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/domain-whitelist-source-range: 1.1.X.X,2.2.2.2
  name: demo-domain
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact
          - backend:
              service:
                name: app-service
                port:
                  number: 80
            path: /app
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/whitelist-source-range: 3.3.X.X
  name: demo-route
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /order
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/domain-whitelist-source-range: 1.1.X.X,2.2.2.2
  name: demo-domain
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80
          - path: /app
            backend:
              serviceName: app-service
              servicePort: 80
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/whitelist-source-range: 3.3.X.X
  name: demo-route
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /order
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Pembatasan laju gateway tunggal

MSE Ingress mendukung pembatasan laju per instans gateway di tingkat entri rute. Batasan ini berlaku untuk satu replika gateway, bukan untuk seluruh kluster gateway.

Untuk pembatasan laju tingkat kluster, gunakan kontrol pembatasan laju global.

Anotasi	Deskripsi	Bawaan
`mse.ingress.kubernetes.io/route-limit-rpm`	Maksimum permintaan per menit (RPM) pada satu instans gateway. Batas burst = RPM × `route-limit-burst-multiplier`. Saat batas terlampaui, badan respons adalah `local_rate_limited`. Kode status: 503 untuk versi gateway sebelum v1.2.23; 429 untuk v1.2.23 dan lebih baru.	—
`mse.ingress.kubernetes.io/route-limit-rps`	Maksimum permintaan per detik (RPS) pada satu instans gateway. Batas burst = RPS × `route-limit-burst-multiplier`. Saat batas terlampaui, badan respons adalah `local_rate_limited`. Kode status: 503 untuk versi gateway sebelum v1.2.23; 429 untuk v1.2.23 dan lebih baru.	—
`mse.ingress.kubernetes.io/route-limit-burst-multiplier`	Pengali yang diterapkan pada RPM atau RPS untuk menghitung batas burst.	`5`

Contoh 1: Batasi berdasarkan RPM

Atur maksimum 100 RPM dengan batas burst 200 (pengali = 2) untuk example.com/test.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/route-limit-rpm: "100"
    mse.ingress.kubernetes.io/route-limit-burst-multiplier: "2"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/route-limit-rpm: "100"
    mse.ingress.kubernetes.io/route-limit-burst-multiplier: "2"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Contoh 2: Batasi berdasarkan RPS

Atur maksimum 10 RPS dengan pengali burst bawaan (5, memberikan batas burst 50) untuk example.com/test.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/route-limit-rps: "10"
    # Pengali burst bawaan adalah 5; batas burst = 10 x 5 = 50
    # mse.ingress.kubernetes.io/route-limit-burst-multiplier: "5"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/route-limit-rps: "10"
    # mse.ingress.kubernetes.io/route-limit-burst-multiplier: "5"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Kontrol pembatasan laju global

MSE Ingress terintegrasi dengan Sentinel untuk memberlakukan batas RPS tingkat kluster pada entri rute di seluruh kluster gateway.

Fitur ini memerlukan versi gateway MSE Ingress 1.2.25 atau lebih baru.

Gunakan mse.ingress.kubernetes.io/rate-limit untuk mengatur RPS maksimum untuk entri rute. Saat batas terlampaui, respons bawaan adalah kode status 429 dengan badan sentinel rate limited. Konfigurasikan perilaku pembatasan laju kustom menggunakan salah satu dari dua metode di bawah — respons kustom atau pengalihan. Hanya satu metode yang dapat aktif sekaligus.

Respons kustom

Anotasi	Deskripsi	Bawaan
`mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code`	Kode status HTTP saat batas terlampaui.	`429`
`mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type`	Content-Type badan respons: `text` → `text/plain; charset=UTF-8`; `json` → `application/json; charset=UTF-8`.	`text`
`mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body`	Isi badan respons saat batas terlampaui.	`sentinel rate limited`

Contoh 1: Terapkan batas RPS tingkat kluster dengan perilaku bawaan

Batasi example.com/test hingga 100 RPS tingkat kluster.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/rate-limit: "100"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/rate-limit: "100"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Contoh 2: Kembalikan respons error kustom saat batas terlampaui

Batasi example.com/test hingga 100 RPS, kembalikan kode status 503 dengan badan server is overload.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/rate-limit: "100"
    mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code: 503
    mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body: "server is overload"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/rate-limit: "100"
    mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code: 503
    mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body: "server is overload"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Pengalihan

Gunakan mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url untuk mengalihkan klien ke URL fallback saat batas terlampaui.

Example: Batasi example.com/test hingga 100 RPS dan alihkan ke example.com/fallback saat batas tercapai.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/rate-limit: "100"
    mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url: "example.com/fallback"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/rate-limit: "100"
    mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url: "example.com/fallback"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Kontrol konkurensi global

MSE Ingress terintegrasi dengan Sentinel untuk memberlakukan batas tingkat kluster pada jumlah permintaan sedang berlangsung untuk entri rute.

Fitur ini memerlukan versi gateway MSE Ingress 1.2.25 atau lebih baru.

Gunakan mse.ingress.kubernetes.io/concurrency-limit untuk mengatur jumlah maksimum permintaan konkuren untuk entri rute di seluruh kluster gateway. Saat batas terlampaui, respons bawaan adalah kode status 429 dengan badan sentinel rate limited. Konfigurasikan perilaku konkurensi kustom menggunakan salah satu dari dua metode di bawah — respons kustom atau pengalihan. Hanya satu metode yang dapat aktif sekaligus.

Respons kustom

Anotasi	Deskripsi	Bawaan
`mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code`	Kode status HTTP saat batas terlampaui.	`429`
`mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type`	Content-Type badan respons: `text` → `text/plain; charset=UTF-8`; `json` → `application/json; charset=UTF-8`.	`text`
`mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body`	Isi badan respons saat batas terlampaui.	`sentinel rate limited`

Contoh 1: Terapkan batas konkurensi dengan perilaku bawaan

Batasi permintaan konkuren ke example.com/test hingga 1000 di seluruh kluster.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/concurrency-limit: "1000"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/concurrency-limit: "1000"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Contoh 2: Kembalikan respons error kustom saat batas terlampaui

Batasi konkurensi hingga 1000 dan kembalikan kode status 503 dengan badan server is overload.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/concurrency-limit: "1000"
    mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code: 503
    mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body: "server is overload"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/concurrency-limit: "1000"
    mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code: 503
    mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body: "server is overload"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Pengalihan

Gunakan mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url untuk mengalihkan klien ke URL fallback saat batas terlampaui.

Example: Batasi konkurensi hingga 1000 dan alihkan ke example.com/fallback saat batas tercapai.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/concurrency-limit: "1000"
    mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url: "example.com/fallback"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/concurrency-limit: "1000"
    mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url: "example.com/fallback"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Pencerminan lalu lintas

Pencerminan lalu lintas menyalin lalu lintas langsung ke layanan bayangan tanpa memengaruhi jalur permintaan utama. Gateway meneruskan salinan setiap permintaan ke target cermin dan membuang responsnya — permintaan yang dicerminkan bersifat fire-and-forget dan tidak memengaruhi latensi atau hasil permintaan asli. Hal ini membuat pencerminan lalu lintas cocok untuk menguji versi layanan baru, audit operasional, dan analisis lalu lintas.

Saat permintaan dicerminkan, MSE Ingress secara otomatis menambahkan -shadow ke header Host dalam permintaan yang disalin (misalnya, example.com menjadi example.com-shadow).

Anotasi	Deskripsi	Bawaan
`mse.ingress.kubernetes.io/mirror-target-service`	Layanan tujuan untuk lalu lintas yang dicerminkan. Format: `namespace/name:port`. `namespace` dan `Port` bersifat opsional.	—
`mse.ingress.kubernetes.io/mirror-percentage`	Persentase lalu lintas yang dicerminkan. Bilangan bulat dari 0 hingga 100.	`100`

Contoh 1: Mirror semua lalu lintas

Salin semua permintaan ke example.com/test ke layanan test/app:8080.

Header Host dalam permintaan yang dicerminkan secara otomatis diubah menjadi example.com-shadow. Respons dari target bayangan dibuang.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/mirror-target-service: test/app:8080
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/mirror-target-service: test/app:8080
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Contoh 2: Cermin persentase lalu lintas

Salin 10% permintaan ke example.com/test ke test/app:8080.

Header Host dalam permintaan yang dicerminkan secara otomatis diubah menjadi example.com-shadow. Respons dari target bayangan dibuang.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/mirror-target-service: test/app:8080
    mse.ingress.kubernetes.io/mirror-percentage: 10
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/mirror-target-service: test/app:8080
    mse.ingress.kubernetes.io/mirror-percentage: 10
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Protokol layanan backend: HTTPS dan gRPC

Secara bawaan, MSE Ingress menggunakan HTTP untuk meneruskan permintaan ke layanan backend. Gunakan anotasi nginx.ingress.kubernetes.io/backend-protocol untuk beralih ke HTTPS atau gRPC.

Jika grpc atau http2 diatur sebagai name port dalam spesifikasi Service Kubernetes, MSE Ingress secara otomatis menggunakan gRPC atau HTTP/2 untuk meneruskan permintaan — anotasi backend-protocol: "GRPC" tidak diperlukan. Ini berbeda dari perilaku NGINX Ingress standar.

Contoh 1: Teruskan menggunakan HTTPS

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Contoh 2: Teruskan menggunakan gRPC

Dua metode tersedia. Gunakan metode 1 (anotasi) untuk kontrol eksplisit, atau metode 2 (nama port Service) untuk mendeteksi gRPC secara otomatis.

Metode 1: Gunakan anotasi

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Metode 2: Gunakan nama port Service

Atur name: grpc dalam spesifikasi Service. MSE Ingress mendeteksi ini secara otomatis dan menggunakan gRPC tanpa memerlukan anotasi.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /order
            pathType: Exact
---
apiVersion: v1
kind: Service
metadata:
  name: demo-service
spec:
  ports:
    - name: grpc
      port: 80
      protocol: TCP
  selector:
    app: demo-service

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: demo-service
spec:
  ports:
    - name: grpc
      port: 80
      protocol: TCP
  selector:
    app: demo-service

</details>

Algoritma penyeimbangan beban untuk layanan backend

Algoritma penyeimbangan beban menentukan bagaimana gateway memilih node backend saat meneruskan permintaan.

Algoritma penyeimbangan beban umum

Gunakan nginx.ingress.kubernetes.io/load-balance untuk mengatur algoritma. Bawaan: round_robin.

Nilai	Algoritma
`round_robin`	Round robin
`least_conn`	Least connections
`random`	Random

Penting

Algoritma exponentially weighted moving average (EWMA) tidak didukung oleh gateway cloud-native. Jika EWMA dikonfigurasi, sistem akan kembali ke round robin.

Example: Gunakan penyeimbangan beban least connections untuk demo-service.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/load-balance: "least_conn"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /order
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/load-balance: "least_conn"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Hashing konsisten

Gunakan nginx.ingress.kubernetes.io/upstream-hash-by untuk mengaktifkan hashing konsisten. Permintaan dengan kunci hash yang sama selalu diteruskan ke node backend yang sama. Kunci hash dapat berasal dari variabel NGINX, header permintaan, atau parameter kueri.

Format kunci hash	Deskripsi
`$request_uri`	Path permintaan lengkap termasuk parameter kueri
`$host`	Host permintaan
`$remote_addr`	Alamat IP klien
`$http_<header-name>`	Nilai header permintaan tertentu (misalnya, `$http_x-stage`)
`$arg_<param-name>`	Nilai parameter kueri (misalnya, `$arg_x-stage`)

Contoh 1: Hash berdasarkan alamat IP klien

Permintaan dari alamat IP klien yang sama selalu diarahkan ke node backend yang sama.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$remote_addr"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$remote_addr"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Contoh 2: Hash berdasarkan header permintaan

Permintaan dengan nilai header X-Stage yang sama selalu diarahkan ke node backend yang sama.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$http_x-stage"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$http_x-stage"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Contoh 3: Hash berdasarkan parameter kueri

Permintaan dengan nilai parameter kueri X-Stage yang sama selalu diarahkan ke node backend yang sama.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_x-stage"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_x-stage"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Pra-ambil layanan (warmup)

Pra-ambil layanan secara bertahap meningkatkan lalu lintas ke node backend yang baru ditambahkan selama periode warmup tertentu. Ini mencegah cold start membebani node sebelum sepenuhnya diinisialisasi.

Gunakan mse.ingress.kubernetes.io/warmup untuk mengatur periode warmup dalam detik. Fitur ini dinonaktifkan secara bawaan.

Pra-ambil layanan hanya berfungsi dengan algoritma penyeimbangan beban round robin dan least connections.

Example: Aktifkan jendela warmup 30 detik untuk demo-service.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/warmup: "30"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/warmup: "30"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Afinitas cookie (persistensi sesi)

Afinitas cookie memastikan bahwa permintaan dari klien yang sama selalu diarahkan ke node backend yang sama. Saat klien mengirim permintaan tanpa cookie yang cocok, MSE Ingress menghasilkan dan mengembalikan cookie. Permintaan berikutnya yang menyertakan cookie ini diarahkan ke node yang sama.

Anotasi	Deskripsi	Bawaan
`nginx.ingress.kubernetes.io/affinity`	Jenis afinitas. Satu-satunya nilai yang valid adalah `cookie`.	—
`nginx.ingress.kubernetes.io/affinity-mode`	Mode afinitas. Satu-satunya nilai yang valid adalah `balanced`.	`balanced`
`nginx.ingress.kubernetes.io/session-cookie-name`	Nama cookie yang digunakan sebagai kunci hash.	`INGRESSCOOKIE`
`nginx.ingress.kubernetes.io/session-cookie-path`	Path cookie yang dihasilkan.	`/`
`nginx.ingress.kubernetes.io/session-cookie-max-age`	Waktu kedaluwarsa cookie yang dihasilkan, dalam detik.	Tingkat sesi
`nginx.ingress.kubernetes.io/session-cookie-expires`	Waktu kedaluwarsa cookie yang dihasilkan, dalam detik.	Tingkat sesi

Contoh 1: Aktifkan afinitas cookie dengan pengaturan bawaan

Nama cookie: INGRESSCOOKIE, path: /, kedaluwarsa tingkat sesi.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Contoh 2: Nama cookie dan kedaluwarsa kustom

Nama cookie: test, path: /, kedaluwarsa: 10 detik.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
    nginx.ingress.kubernetes.io/session-cookie-name: "test"
    nginx.ingress.kubernetes.io/session-cookie-max-age: "10"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/affinity: "cookie"
    nginx.ingress.kubernetes.io/session-cookie-name: "test"
    nginx.ingress.kubernetes.io/session-cookie-max-age: "10"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Kolam koneksi antara gateway dan layanan backend

Konfigurasikan kolam koneksi untuk layanan backend guna membatasi jumlah koneksi simultan antara gateway dan layanan tersebut. Ini melindungi backend dari kelebihan beban.

Anotasi	Deskripsi
`mse.ingress.kubernetes.io/connection-policy-tcp-max-connection`	Koneksi total maksimum antara gateway dan layanan backend.
`mse.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint`	Koneksi maksimum antara gateway dan satu node backend.
`mse.ingress.kubernetes.io/connection-policy-http-max-request-per-connection`	Permintaan HTTP maksimum per koneksi antara gateway dan layanan backend.

Example: Untuk demo-service, batasi koneksi total hingga 10 dan koneksi per node hingga 2.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/connection-policy-tcp-max-connection: 10
    mse.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint: 2
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/connection-policy-tcp-max-connection: 10
    mse.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint: 2
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

Versi TLS dan paket sandi untuk koneksi klien ke gateway

Secara bawaan, MSE Ingress menerima koneksi TLS dari TLSv1.0 hingga TLSv1.3. Paket sandi berikut diaktifkan secara bawaan:

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

Gunakan anotasi berikut untuk membatasi versi TLS dan paket sandi untuk domain tertentu.

Anotasi	Deskripsi	Bawaan
`mse.ingress.kubernetes.io/tls-min-protocol-version`	Versi TLS minimum. Nilai yang valid: `TLSv1.0`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`.	`TLSv1.0`
`mse.ingress.kubernetes.io/tls-max-protocol-version`	Versi TLS maksimum.	`TLSv1.3`
`nginx.ingress.kubernetes.io/ssl-cipher`	Paket sandi TLS. Dipisahkan koma. Berlaku hanya untuk proses jabat tangan TLS menggunakan TLSv1.0–TLSv1.2.	—

Example: Batasi example.com hanya ke TLSv1.2.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/tls-min-protocol-version: "TLSv1.2"
    mse.ingress.kubernetes.io/tls-max-protocol-version: "TLSv1.2"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    mse.ingress.kubernetes.io/tls-min-protocol-version: "TLSv1.2"
    mse.ingress.kubernetes.io/tls-max-protocol-version: "TLSv1.2"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>

TLS mutual antara gateway dan layanan backend

Secara bawaan, MSE Ingress menggunakan HTTP untuk meneruskan permintaan ke layanan backend. Saat nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" diatur, MSE Ingress menggunakan TLS satu arah — gateway mengautentikasi sertifikat layanan backend, yang harus dikeluarkan oleh Otoritas Sertifikat (CA) terkenal.

Untuk TLS mutual (mTLS), kedua pihak saling mengautentikasi sertifikatnya: gateway memverifikasi sertifikat backend dan layanan backend memverifikasi sertifikat klien gateway.

Annotasi	Deskripsi
`nginx.ingress.kubernetes.io/proxy-ssl-secret`	Sertifikat klien yang digunakan oleh gerbang untuk mTLS. Format: `secretNamespace/secretName`.
`nginx.ingress.kubernetes.io/proxy-ssl-name`	Nilai Server Name Indication (SNI) yang digunakan selama proses jabat tangan TLS.
`nginx.ingress.kubernetes.io/proxy-ssl-server-name`	Mengaktifkan atau menonaktifkan SNI selama proses jabat tangan TLS.

Example: Konfigurasikan mTLS menggunakan sertifikat klien yang disimpan dalam Secret gateway-cert di namespace default.

# Kubernetes v1.19 dan lebih baru
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-ssl-secret: "default/gateway-cert"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port:
                  number: 80
            path: /test
            pathType: Exact

<details> <summary>Kubernetes sebelum v1.19</summary>

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-ssl-secret: "default/gateway-cert"
  name: demo
spec:
  ingressClassName: mse
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

</details>