Microservices Engine:Anotasi yang didukung oleh gerbang MSE Ingress

Lingkup

Setiap anotasi berlaku pada salah satu dari tiga tingkat berikut:

Awalan

Gerbang MSE Ingress menerima awalan nginx.ingress.kubernetes.io/ dan mse.ingress.kubernetes.io/ untuk anotasi yang kompatibel. Gunakan salah satu awalan sesuai preferensi Anda.

Anotasi eksklusif MSE hanya mendukung awalan mse.ingress.kubernetes.io/.

Format nilai anotasi

Anotasi Kubernetes selalu berupa string. Konvensi pengkodean berikut berlaku:

Aturan preseden dan interaksi

Catatan kompatibilitas

• Variabel NGINX: MSE mengimplementasikan fitur secara berbeda dari NGINX. Variabel NGINX yang dikonfigurasi dalam anotasi atau potongan kode tidak kompatibel dengan MSE.

• Perilaku proxy-body-size: Gerbang cloud-native MSE menggunakan enkode transfer chunked, yang secara otomatis memecah badan permintaan besar menjadi chunk. Untuk menangani transfer file besar, sesuaikan parameter DownstreamConnectionBufferLimits di Pengaturan Parameter untuk gerbang MSE Anda.

Rilis canary

# Rilis canary: arahkan traffic berdasarkan nilai header
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: canary-ingress
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "x-canary"
    nginx.ingress.kubernetes.io/canary-by-header-value: "true"
spec:
  rules:
    - host: example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: my-service-canary
                port:
                  number: 80

Routing multi-layanan

Arahkan traffic ke beberapa layanan backend dengan distribusi berbasis bobot.

Sintaks: {weight}% {serviceName}.{serviceNamespace}.svc.cluster.local:{port}

annotations:
  # Arahkan 60% traffic ke foo dan 40% ke bar
  mse.ingress.kubernetes.io/destination: |
    60% foo.default.svc.cluster.local:8080
    40% bar.default.svc.cluster.local:9090

Setelah Anda mengonfigurasi anotasi ini, semua aturan routing pada Ingress diarahkan ke layanan yang ditentukan. Jika sintaks tidak valid, anotasi diabaikan dan aturan routing asli tetap tidak berubah.

Subset layanan

Arahkan traffic ke subset pod dalam suatu layanan, berguna ketika satu layanan mengelola beberapa deployment.

Cara service-subset mengarahkan traffic:

• Tanpa konfigurasi subset-labels:

  • Diatur ke "" atau base: Mengarahkan ke pod dengan label opensergo.io/canary: "" atau pod tanpa kunci label opensergo.io/canary.

  • Diatur ke nilai lain (misalnya, gray): Mengarahkan ke pod dengan label opensergo.io/canary-gray: gray.

• Dengan konfigurasi subset-labels: Hanya mengarahkan ke pod yang labelnya sesuai dengan pasangan kunci:nilai yang didefinisikan dalam subset-labels.

Jika tidak ada pod yang cocok dengan label yang ditentukan, traffic secara otomatis diarahkan ke semua pod dalam layanan tersebut.

annotations:
  # Arahkan traffic ke pod yang dilabeli sebagai subset "gray"
  mse.ingress.kubernetes.io/service-subset: "gray"

Fallback

Pencocokan regex

Menulis ulang

Pengalihan

Beberapa versi NGINX Ingress mendukung variabel NGINX untuk pengalihan, tetapi ini tidak didokumentasikan dalam referensi resmi Anotasi dan dapat menyebabkan masalah ketidakkompatibilitas. Hindari penggunaan variabel NGINX untuk pengalihan.

CORS

Kontrol header

Manipulasi header permintaan dan respons di tingkat gateway. Anotasi kontrol header untuk rute dasar dan rute canary bersifat independen—konfigurasikan kebijakan header yang berbeda untuk masing-masing.

Header permintaan:

Header respons:

Sintaksis untuk menambahkan dan memperbarui anotasi:

• Header tunggal: key value

• Beberapa header: Gunakan pipe YAML (|), satu pasangan kunci-nilai per baris.

Sintaks untuk menghapus anotasi:

• Header tunggal: key

• Beberapa header: Pisahkan dengan koma (,).

annotations:
  # Tambahkan header kustom ke permintaan
  mse.ingress.kubernetes.io/request-header-control-add: "x-request-id 12345"
  # Tambahkan beberapa header ke respons
  mse.ingress.kubernetes.io/response-header-control-add: |
    x-custom-header value1
    x-another-header value2
  # Hapus header dari respons
  mse.ingress.kubernetes.io/response-header-control-remove: "x-powered-by,server"

Timeout

Timeout ini berlaku di lapisan aplikasi, bukan di lapisan transport TCP.

annotations:
  mse.ingress.kubernetes.io/timeout: "30"

Retry

Mirror traffic

Parameter mirror-target-service:

annotations:
  # Mirror 50% traffic ke layanan shadow
  mse.ingress.kubernetes.io/mirror-target-service: "default/shadow-service:8080"
  mse.ingress.kubernetes.io/mirror-percentage: "50"

Alias domain

Pembatasan laju

annotations:
  # Batasi hingga 100 RPS dengan respons JSON kustom
  mse.ingress.kubernetes.io/rate-limit: "100"
  mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code: "429"
  mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type: "JSON"
  mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body: '{"error":"rate limit exceeded"}'

Kontrol konkurensi

Kontrol konkurensi global membatasi jumlah permintaan yang diproses secara bersamaan pada suatu rute.

annotations:
  # Batasi hingga 50 permintaan konkuren dengan pengalihan saat overflow
  mse.ingress.kubernetes.io/concurrency-limit: "50"
  mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url: "https://example.com/busy"

Protokol backend

Penyeimbangan beban

Metode hashing konsisten yang didukung:

• Variabel NGINX: $request_uri (path permintaan termasuk parameter), $host (host permintaan), $remote_addr (alamat IP klien)

• Header permintaan: $http_headerName

• Parameter path permintaan: $arg_varName

Start graceful (prefetching layanan)

annotations:
  # Panaskan pod baru selama 60 detik
  mse.ingress.kubernetes.io/warmup: "60"

Afinitas cookie

Kontrol akses IP

Aturan prioritas:

• Daftar IP tingkat rute mengungguli daftar IP tingkat domain.

• nginx.ingress.kubernetes.io/denylist-source-range mengungguli mse.ingress.kubernetes.io/blacklist-source-range.

annotations:
  # Izinkan hanya IP tertentu di tingkat rute
  nginx.ingress.kubernetes.io/whitelist-source-range: "10.0.0.0/8,192.168.1.100"

Kolam koneksi gateway-ke-backend

annotations:
  # Batasi kolam koneksi ke backend
  mse.ingress.kubernetes.io/connection-policy-tcp-max-connection: "1024"
  mse.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint: "100"
  mse.ingress.kubernetes.io/connection-policy-http-max-request-per-connection: "500"

TLS klien-ke-gateway

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

annotations:
  # Terapkan minimum TLS 1.2
  mse.ingress.kubernetes.io/tls-min-protocol-version: "TLSv1.2"
  mse.ingress.kubernetes.io/tls-max-protocol-version: "TLSv1.2"

TLS gateway-ke-backend

Otentikasi

annotations:
  # Otentikasi basic dengan rahasia Kubernetes
  nginx.ingress.kubernetes.io/auth-type: "basic"
  nginx.ingress.kubernetes.io/auth-secret: "default/my-auth-secret"
  nginx.ingress.kubernetes.io/auth-secret-type: "auth-file"
  nginx.ingress.kubernetes.io/auth-realm: "Protected Area"