Aktifkan rilis canary, CORS & kebijakan retry melalui APIG Ingress - API Gateway

Dalam kluster Kubernetes, APIG Ingress mengelola objek API yang dapat diakses secara eksternal untuk layanan dan menyediakan load balancing lapisan 7. Topik ini menjelaskan fitur-fitur tingkat lanjut APIG Ingress untuk mengelola traffic ingress dalam kluster Anda.

Rilis Canary

APIG Ingress mendukung routing canggih, termasuk rilis canary berdasarkan header permintaan, parameter kueri, cookie, dan bobot. Konfigurasikan rilis canary menggunakan anotasi. Untuk mengaktifkan rilis canary, atur anotasi nginx.ingress.kubernetes.io/canary: "true". Anotasi yang berbeda mengaktifkan kemampuan rilis canary yang berbeda.

Catatan

Ketika beberapa metode canary dikonfigurasi, urutan prioritasnya adalah berbasis header atau parameter kueri, lalu berbasis cookie, kemudian berbasis bobot.

Rilis Canary Berbasis Header

Konfigurasikan hanya nginx.ingress.kubernetes.io/canary-by-header: Trafik dibagi berdasarkan header permintaan. Jika nilai header yang dikonfigurasi adalah always, trafik diarahkan ke titik akhir layanan canary. Jika tidak, trafik diarahkan ke layanan stabil.
Konfigurasikan kedua anotasi nginx.ingress.kubernetes.io/canary-by-header-value dan nginx.ingress.kubernetes.io/canary-by-header: Trafik diarahkan ke layanan canary hanya jika header permintaan dan nilainya sesuai dengan konfigurasi. Jika tidak, trafik diarahkan ke layanan stabil.

Catatan

Berbeda dengan NGINX Ingress dan ALB Ingress yang mendukung hingga dua versi layanan untuk rilis canary, APIG Ingress mendukung jumlah versi layanan yang tidak terbatas.

Contoh:

Jika header permintaan adalah apig: always, permintaan mengakses layanan canary `demo-service-canary`. Jika tidak, permintaan mengakses layanan stabil `demo-service`. Konfigurasikan sebagai berikut:

Kluster dengan versi 1.19 dan yang lebih baru

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "apig"
  name: demo-canary
spec:
  ingressClassName: apig
  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: apig
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /hello
            pathType: Exact

Kluster dengan versi sebelum 1.19

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

Jika header permintaan adalah apig: v1, permintaan mengakses layanan canary `demo-service-canary-v1`. Jika header permintaan adalah apig: v2, permintaan mengakses layanan canary `demo-service-canary-v2`. Jika tidak, permintaan mengakses layanan stabil `demo-service`. Konfigurasikan sebagai berikut:

Kluster dengan versi 1.19 dan yang lebih baru

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "apig"
    nginx.ingress.kubernetes.io/canary-by-header-value: "v1"
  name: demo-canary-v1
spec:
  ingressClassName: apig
  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: "apig"
    nginx.ingress.kubernetes.io/canary-by-header-value: "v2"
  name: demo-canary-v2
spec:
  ingressClassName: apig
  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: apig
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /hello
            pathType: Exact

Kluster dengan versi sebelum 1.19

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

Rilis Canary Berbasis Parameter Kueri

Konfigurasikan hanya higress.ingress.kubernetes.io/canary-by-query
Trafik dibagi berdasarkan parameter kueri URL. Jika URL permintaan berisi kunci parameter kueri yang dikonfigurasi dengan nilai always, trafik diarahkan ke titik akhir layanan canary. Jika tidak, trafik diarahkan ke layanan stabil.
Konfigurasikan kedua anotasi higress.ingress.kubernetes.io/canary-by-query-value dan higress.ingress.kubernetes.io/canary-by-query
Trafik diarahkan ke layanan canary hanya jika kunci parameter kueri dan nilai parameter kueri permintaan sesuai dengan konfigurasi. Jika tidak, trafik diarahkan ke layanan stabil.
Catatan
Gunakan rilis canary berbasis header dan berbasis parameter kueri secara bersamaan. Trafik diarahkan ke layanan canary hanya jika kedua kondisi terpenuhi.

Contoh:

Jika URL permintaan mencakup parameter kueri canary: gray, permintaan mengakses layanan canary `demo-service-canary`. Jika tidak, permintaan mengakses layanan stabil `demo-service`. Konfigurasikan sebagai berikut:

Kluster dengan versi 1.19 dan yang lebih baru

apiVersion:networking.k8s.io/v1 
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    higress.ingress.kubernetes.io/canary-by-query: "canary"
    higress.ingress.kubernetes.io/canary-by-query-value: "gray"
  name: demo-canary
spec:
  ingressClassName: apig
  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: apig
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /hello
            pathType: Exact

Kluster dengan versi sebelum 1.19

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

Jika URL permintaan mencakup parameter kueri canary: gray dan header permintaan mencakup x-user-id: test, permintaan mengakses layanan canary `demo-service-canary`. Jika tidak, permintaan mengakses layanan stabil `demo-service`. Konfigurasikan sebagai berikut:

Kluster dengan versi 1.19 dan yang lebih baru

apiVersion:networking.k8s.io/v1 
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    higress.ingress.kubernetes.io/canary-by-query: "canary"
    higress.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: apig
  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: apig
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /hello
            pathType: Exact

Kluster dengan versi sebelum 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    higress.ingress.kubernetes.io/canary-by-query: "canary"
    higress.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: apig
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service-canary
              servicePort: 80
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: apig
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service
              servicePort: 80

Rilis Canary Berbasis Cookie

nginx.ingress.kubernetes.io/canary-by-cookie: Trafik dibagi berdasarkan cookie. Jika nilai cookie yang dikonfigurasi adalah always, trafik diarahkan ke layanan canary; jika tidak, trafik diarahkan ke layanan stabil.

Catatan

Rilis canary berbasis cookie tidak mendukung nilai kustom. Nilai cookie yang dikonfigurasi harus always.

Contohnya, jika cookie permintaan adalah demo=always, permintaan mengakses layanan canary `demo-service-canary`. Jika tidak, permintaan mengakses layanan stabil `demo-service`. Konfigurasikan sebagai berikut:

Kluster dengan versi 1.19 dan yang 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: apig
  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: apig
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /hello
            pathType: Exact

Kluster dengan versi sebelum 1.19

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: apig
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service-canary
              servicePort: 80
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: apig
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service
              servicePort: 80

Rilis Canary Berbasis Bobot

Anotasi	Deskripsi
nginx.ingress.kubernetes.io/canary-weight	Atur persentase permintaan yang diarahkan ke layanan tertentu (bilangan bulat dari 0 hingga 100).
nginx.ingress.kubernetes.io/canary-weight-total	Atur total bobot. Nilai default adalah 100.

Contohnya, tetapkan bobot 30% untuk layanan canary `demo-service-canary-v1`, bobot 20% untuk layanan canary `demo-service-canary-v2`, dan bobot 50% untuk layanan stabil `demo-service`. Konfigurasikan sebagai berikut:

Kluster dengan versi 1.19 dan yang 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: apig
  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: apig
  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: apig
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /hello
            pathType: Exact

Kluster dengan versi sebelum 1.19

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: apig
  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: apig
  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: apig
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service
              servicePort: 80

Subset Layanan

Subset layanan diterapkan ketika sebuah Service dikaitkan dengan beberapa deployment. Ingress meneruskan permintaan ke subset pod di bawah Service tersebut, biasanya ke pod dalam Service yang memiliki label tertentu. Anda dapat mengonfigurasi ini dengan dua cara:

Gunakan Label Pod yang Didefinisikan oleh APIG Ingress

Anda dapat mengatur versi Service menggunakan anotasi higress.ingress.kubernetes.io/service-subset. Secara default, APIG Ingress mengaitkan versi layanan yang dikonfigurasi dengan label Pod yang diawali dengan `opensergo.io/canary`. Anotasi ini menentukan hal berikut:

Jika dikonfigurasi sebagai "" atau base, permintaan diteruskan ke pod dengan label opensergo.io/canary: "" atau ke pod tanpa kunci label apa pun yang diawali dengan opensergo.io/canary. Ini mencakup pod dengan label kosong atau tanpa label.
Jika dikonfigurasi dengan nilai lain, permintaan diteruskan ke pod dengan label opensergo.io/canary-{nilai lain}: {nilai lain}. Misalnya, jika dikonfigurasi sebagai gray, permintaan diteruskan ke pod dengan label opensergo.io/canary-gray: gray.

Contohnya, sebuah Service Kubernetes bernama `go-httpbin` dikaitkan dengan dua deployment. Satu deployment mengelola pod tanpa kunci label apa pun yang diawali dengan opensergo.io/canary. Deployment lainnya mengelola pod dengan label canary opensergo.io/canary-gray: gray. Konfigurasikan sebagai berikut:

# go-httpbin k8s service
apiVersion: v1
kind: Service
metadata:
  name: go-httpbin
  namespace: default
spec:
  ports:
    - port: 8080
      protocol: TCP
  selector:
    app: go-httpbin
---
# go-httpbin base deployment
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/apig/go-httpbin
          args:
            - "--version=base"
          imagePullPolicy: Always
          name: go-httpbin
---
# go-httpbin gray deployment
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/apig/go-httpbin
          args:
            - "--version=gray"
          imagePullPolicy: Always
          name: go-httpbin

Untuk meneruskan permintaan untuk example.com/test ke go-httpbin-gray jika header permintaan mencakup x-user-id: test, dan ke go-httpbin-base jika tidak, konfigurasikan sebagai berikut:

Kluster dengan versi 1.19 dan yang 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"
    # Forward requests to pods with the canary label opensergo.io/canary-gray: gray
    higress.ingress.kubernetes.io/service-subset: gray
  name: demo-canary
  namespace: default
spec:
  ingressClassName: apig
  rules:
    - http:
        paths:
          - backend:
              service:
                name: go-httpbin
                port: 
                  number: 8080
            path: /test
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    # Forward requests to pods without a label prefixed with opensergo.io/canary
    higress.ingress.kubernetes.io/service-subset: ""
  name: demo
  namespace: default
spec:
  ingressClassName: apig
  rules:
    - http:
        paths:
          - backend:
              service:
                name: go-httpbin
                port: 
                  number: 8080
            path: /test
            pathType: Exact

Kluster dengan versi sebelum 1.19

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"
    # Forward requests to pods with the canary label opensergo.io/canary-gray: gray
    higress.ingress.kubernetes.io/service-subset: gray
  name: demo-canary
  namespace: default
spec:
  ingressClassName: apig
  rules:
    - http:
        paths:
          - path: /test
            backend:
              # Configure the service as go-httpbin, but specify the version in the annotation.
              serviceName: go-httpbin
              servicePort: 8080
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    # Forward requests to pods without a label prefixed with opensergo.io/canary
    higress.ingress.kubernetes.io/service-subset: ""
  name: demo
  namespace: default
spec:
  ingressClassName: apig
  rules:
    - http:
        paths:
          - path: /test
            backend:
              # Configure the service as go-httpbin, but specify the version in the annotation.
              serviceName: go-httpbin
              servicePort: 8080

Gunakan Label Kustom

Konfigurasikan kedua anotasi higress.ingress.kubernetes.io/service-subset dan higress.ingress.kubernetes.io/subset-labels untuk mendefinisikan pod subset menggunakan label kustom.

Catatan

Subset ini tidak dikaitkan dengan label yang diawali dengan opensergo.io/canary.

Contohnya, sebuah Service Kubernetes bernama go-httpbin dikaitkan dengan dua deployment. Satu deployment mengelola pod tanpa kunci label apa pun yang diawali dengan opensergo.io/canary. Deployment lainnya mengelola pod dengan label canary version: gray. Konfigurasikan sebagai berikut:

# go-httpbin k8s service
apiVersion: v1
kind: Service
metadata:
  name: go-httpbin
  namespace: default
spec:
  ports:
    - port: 8080
      protocol: TCP
  selector:
    app: go-httpbin
---
# go-httpbin base deployment
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/apig/go-httpbin
          args:
            - "--version=base"
          imagePullPolicy: Always
          name: go-httpbin
---
# go-httpbin base 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
        version: gray
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/apig/go-httpbin
          args:
            - "--version=gray"
          imagePullPolicy: Always
          name: go-httpbin

Untuk meneruskan permintaan untuk example.com/test ke go-httpbin-gray jika header permintaan mencakup x-user-id: test, dan ke go-httpbin-base jika tidak.

Kluster dengan versi 1.19 dan yang 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"
    # Forward requests to pods with the canary label version: gray
    higress.ingress.kubernetes.io/service-subset: gray
    higress.ingress.kubernetes.io/subset-labels: version gray
  name: demo-canary
  namespace: default
spec:
  ingressClassName: apig
  rules:
    - http:
        paths:
          - backend:
              service:
                name: go-httpbin
                port: 
                  number: 8080
            path: /test
            pathType: Exact
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    # Forward requests to pods without a label prefixed with opensergo.io/canary
    higress.ingress.kubernetes.io/service-subset: ""
  name: demo
  namespace: default
spec:
  ingressClassName: apig
  rules:
    - http:
        paths:
          - backend:
              service:
                name: go-httpbin
                port: 
                  number: 8080
            path: /test
            pathType: Exact

Kluster dengan versi sebelum 1.19

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"
    # Forward requests to pods with the canary label version: gray
    higress.ingress.kubernetes.io/service-subset: gray
    higress.ingress.kubernetes.io/subset-labels: version gray
  name: demo-canary
  namespace: default
spec:
  ingressClassName: apig
  rules:
    - http:
        paths:
          - path: /test
            backend:
              # Configure the service as go-httpbin, but specify the version in the annotation.
              serviceName: go-httpbin
              servicePort: 8080
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    # Forward requests to pods without a label prefixed with opensergo.io/canary
    higress.ingress.kubernetes.io/service-subset: ""
  name: demo
  namespace: default
spec:
  ingressClassName: apig
  rules:
    - http:
        paths:
          - path: /test
            backend:
              # Configure the service as go-httpbin, but specify the version in the annotation.
              serviceName: go-httpbin
              servicePort: 8080

Lintas Domain

Cross-Origin Resource Sharing (CORS) memungkinkan server aplikasi web mengontrol akses lintas domain untuk memastikan transfer data yang aman antar domain. Untuk informasi selengkapnya, lihat Cross-Origin Resource Sharing (CORS).

Anotasi	Deskripsi
nginx.ingress.kubernetes.io/enable-cors	Mengaktifkan atau menonaktifkan CORS.
nginx.ingress.kubernetes.io/cors-allow-origin	Origin yang diizinkan mengakses resource. Pisahkan beberapa origin dengan koma. Karakter wildcard () didukung. Nilai default adalah , yang mengizinkan semua origin.
nginx.ingress.kubernetes.io/cors-allow-methods	Metode permintaan yang diizinkan, seperti GET, POST, dan PUT. Pisahkan beberapa metode dengan koma. Karakter wildcard (*) didukung. Nilai default adalah GET, PUT, POST, DELETE, PATCH, dan OPTIONS.
nginx.ingress.kubernetes.io/cors-allow-headers	Header permintaan yang diizinkan. Pisahkan beberapa header dengan koma. Karakter wildcard (*) didukung. Nilai default adalah DNT, X-CustomHeader, Keep-Alive, User-Agent, X-Requested-With, If-Modified-Since, Cache-Control, Content-Type, dan Authorization.
nginx.ingress.kubernetes.io/cors-expose-headers	Header respons yang dapat diekspos ke browser. Pisahkan beberapa header dengan koma.
nginx.ingress.kubernetes.io/cors-allow-credentials	Menentukan apakah browser dapat mengirim kredensial bersama permintaan. Nilai default adalah true.
nginx.ingress.kubernetes.io/cors-max-age	Waktu maksimum dalam detik hasil permintaan preflight dapat di-cache. Nilai default adalah 1728000.

Contohnya, untuk membatasi permintaan lintas domain hanya ke domain example.com, mengizinkan hanya metode GET dan POST, mengizinkan header permintaan X-Foo-Bar, dan melarang kredensial, gunakan konfigurasi berikut:

Kluster versi 1.19 dan yang 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: apig
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /hello
            pathType: Exact

Kluster sebelum versi 1.19

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: apig
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service
              servicePort: 80

Pencocokan Regex

Ingress Kubernetes standar hanya mendukung pencocokan eksak dan pencocokan awalan. APIG Ingress menambahkan dukungan untuk pencocokan regex. Untuk mengaktifkan pencocokan regex untuk path yang ditentukan dalam spesifikasi Ingress Anda, tambahkan anotasi nginx.ingress.kubernetes.io/use-regex: true.

Contohnya, untuk meneruskan permintaan dengan nama domain example.com dan path yang dimulai dengan /app atau /test ke layanan demo, gunakan konfigurasi berikut:

Kluster menjalankan Kubernetes 1.19 atau yang 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: apig
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo
                port: 
                  number: 8080
            path: /(app|test)/(.*)
            pathType: Prefix

Kluster menjalankan Kubernetes sebelum 1.19

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

Menulis Ulang Path dan Host

Sebelum meneruskan permintaan ke layanan backend target, menulis ulang memodifikasi path dan domain host permintaan asli.

Anotasi	Deskripsi
nginx.ingress.kubernetes.io/rewrite-target	Menulis Ulang Path. Mendukung capturing groups.
nginx.ingress.kubernetes.io/upstream-vhost	Rewrite Host.

Tulis Ulang Jalur

Sebelum meneruskan permintaan example.com/test ke layanan backend, tulis ulang menjadi example.com/dev. Konfigurasikan sebagai berikut:

Kluster pada Kubernetes 1.19 dan yang Lebih Baru

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

Kluster Sebelum Kubernetes 1.19

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

Sebelum meneruskan permintaan apa pun seperti example.com/v1/xxx, yang memiliki awalan /v1/, ke layanan backend, hapus awalan path /v1 dan tulis ulang menjadi example.com/xxx. Konfigurasikan sebagai berikut:

Kluster pada Kubernetes 1.19 dan yang Lebih Baru

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

Kluster Sebelum Kubernetes 1.19

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

Sebelum meneruskan permintaan apa pun seperti example.com/v1/xxx, yang memiliki awalan /v1/, ke layanan backend, ubah awalan path /v1 menjadi /v2 dan tulis ulang menjadi example.com/v2/xxx. Konfigurasikan sebagai berikut:

Kluster pada Kubernetes 1.19 dan yang Lebih Baru

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

Kluster Sebelum Kubernetes 1.19

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

Menulis Ulang Host

Contohnya, sebelum meneruskan permintaan example.com/test ke layanan backend, tulis ulang menjadi test.com/test. Konfigurasikan sebagai berikut:

Kluster pada Kubernetes 1.19 dan yang Lebih Baru

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

Kluster Sebelum Kubernetes 1.19

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

Pengalihan

Pengalihan mengubah permintaan klien asli menjadi permintaan target.

Konfigurasi Pengalihan HTTP ke HTTPS

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

Catatan

APIG Ingress memperlakukan kedua anotasi tersebut sama dan memaksa pengalihan HTTP ke HTTPS.

Contohnya, alihkan http://example.com/test ke https://example.com/test. Konfigurasikan sebagai berikut:

Kluster pada Versi 1.19 dan yang Lebih Baru

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

Kluster Sebelum Versi 1.19

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

Pengalihan Permanen

Anotasi	Deskripsi
nginx.ingress.kubernetes.io/permanent-redirect	URL target untuk pengalihan permanen. Harus mencakup skema (HTTP atau HTTPS).
nginx.ingress.kubernetes.io/permanent-redirect-code	Kode status HTTP untuk pengalihan permanen. Nilai default adalah 301.

Contohnya, alihkan secara permanen http://example.com/test ke http://example.com/app. Konfigurasikan sebagai berikut:

Kluster pada Versi 1.19 dan yang 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: apig
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /test
            pathType: Exact

Kluster Sebelum Versi 1.19

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

Pengalihan Sementara

nginx.ingress.kubernetes.io/temporal-redirect: URL target untuk pengalihan sementara. Harus mencakup skema (HTTP atau HTTPS).

Contohnya, alihkan sementara http://example.com/test ke http://example.com/app. Konfigurasikan sebagai berikut:

Kluster pada Versi 1.19 dan yang 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: apig
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /test
            pathType: Exact

Kluster Sebelum Versi 1.19

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

Kontrol Header

Gunakan kontrol header untuk menambah, menghapus, atau memodifikasi header permintaan sebelum meneruskan permintaan ke layanan backend. Anda juga dapat menambah, menghapus, atau memodifikasi header respons sebelum meneruskan respons ke klien.

Kontrol header permintaan

Anotasi	Deskripsi
higress.ingress.kubernetes.io/request-header-control-add	Tambahkan header yang ditentukan ke permintaan sebelum meneruskannya ke layanan backend. Jika header sudah ada, tambahkan nilai baru ke nilai yang ada. Sintaks: Header tunggal: Key Value. Beberapa header: Gunakan indikator blok literal YAML `\|`. Letakkan setiap pasangan Key Value pada barisnya sendiri.
higress.ingress.kubernetes.io/request-header-control-update	Perbarui header yang ditentukan dalam permintaan sebelum meneruskannya ke layanan backend. Jika header sudah ada, timpa nilainya. Sintaks: Header tunggal: Key Value. Beberapa header: Gunakan indikator blok literal YAML `\|`. Letakkan setiap pasangan Key Value pada barisnya sendiri.
higress.ingress.kubernetes.io/request-header-control-remove	Hapus header yang ditentukan dari permintaan sebelum meneruskannya ke layanan backend. Sintaks: Header tunggal: Key. Beberapa header: Pisahkan kunci dengan koma.

Contoh:

Tambahkan dua header—foo: bar dan test: true—ke permintaan untuk example.com/test. Konfigurasikan sebagai berikut:

Kluster menjalankan Kubernetes 1.19 atau yang lebih baru

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

Kluster menjalankan Kubernetes sebelum 1.19

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

Gabungkan kontrol header dengan rilis canary untuk memberi tag trafik canary. Ketika header permintaan apig: v1 ada, arahkan trafik ke layanan canary demo-service-canary-v1 dan tambahkan header stage: gray. Untuk semua permintaan lainnya, arahkan trafik ke layanan produksi demo-service dan tambahkan header stage: production. Konfigurasikan sebagai berikut:

Kluster menjalankan Kubernetes 1.19 atau yang lebih baru

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "apig"
    nginx.ingress.kubernetes.io/canary-by-header-value: "v1"
    higress.ingress.kubernetes.io/request-header-control-add: "stage gray"
  name: demo-canary-v1
spec:
  ingressClassName: apig
  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:
    higress.ingress.kubernetes.io/request-header-control-add: "stage production"
  name: demo
spec:
  ingressClassName: apig
  rules:
    - http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /hello
            pathType: Exact

Kluster menjalankan Kubernetes sebelum 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-by-header: "apig"
    nginx.ingress.kubernetes.io/canary-by-header-value: "v1"
    higress.ingress.kubernetes.io/request-header-control-add: "stage gray"
  name: demo-canary-v1
spec:
  ingressClassName: apig
  rules:
    - http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service-canary-v1
              servicePort: 80
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    higress.ingress.kubernetes.io/request-header-control-add: |
      foo bar
      test true
  name: demo
spec:
  ingressClassName: apig
  rules:
    - host: example.com 
      http:
        paths:
          - path: /hello
            backend:
              serviceName: demo-service
              servicePort: 80

Kontrol header respons

Anotasi	Deskripsi
higress.ingress.kubernetes.io/response-header-control-add	Tambahkan header yang ditentukan ke respons sebelum meneruskannya ke klien. Jika header sudah ada, tambahkan nilai baru ke nilai yang ada. Sintaks: Header tunggal: Key Value. Beberapa header: Gunakan indikator blok literal YAML `\|`. Letakkan setiap pasangan Key Value pada barisnya sendiri.
higress.ingress.kubernetes.io/response-header-control-update	Perbarui header yang ditentukan dalam respons sebelum meneruskannya ke klien. Jika header sudah ada, timpa nilainya. Sintaks: Header tunggal: Key Value. Beberapa header: Gunakan indikator blok literal YAML `\|`. Letakkan setiap pasangan Key Value pada barisnya sendiri.
higress.ingress.kubernetes.io/response-header-control-remove	Hapus header yang ditentukan dari respons sebelum meneruskannya ke klien. Sintaks: Header tunggal: Key. Beberapa header: Pisahkan kunci dengan koma.

Contohnya, hapus header req-cost-time dari respons terhadap permintaan untuk example.com/test. Konfigurasikan sebagai berikut:

Kluster menjalankan Kubernetes 1.19 atau yang lebih baru

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

Kluster menjalankan Kubernetes sebelum 1.19

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

Retry

APIG Ingress menyediakan pengaturan retry tingkat routing dan secara otomatis mencoba ulang permintaan yang gagal. Atur kondisi retry sesuai kebutuhan—misalnya, untuk upaya koneksi yang gagal, layanan backend yang tidak tersedia, atau respons dengan kode status HTTP tertentu.

Anotasi	Deskripsi
nginx.ingress.kubernetes.io/proxy-next-upstream-tries	Jumlah maksimum percobaan ulang permintaan. Default adalah 3.
nginx.ingress.kubernetes.io/proxy-next-upstream-timeout	Timeout percobaan ulang permintaan dalam detik. Tidak ada timeout yang dikonfigurasi secara default.
nginx.ingress.kubernetes.io/proxy-next-upstream	Kondisi percobaan ulang permintaan, dipisahkan dengan koma. Nilai default adalah `error,timeout`. Nilai yang valid adalah: error: Pembentukan koneksi gagal, atau permintaan menghasilkan error 5xx. timeout: Pembentukan koneksi melebihi waktu, atau permintaan menghasilkan error 5xx. invalid_header: Permintaan menghasilkan error 5xx. http_xxx: Coba ulang untuk kode status HTTP tertentu. Misalnya, http_502, http_403. non_idempotent: Coba ulang untuk permintaan non-idempoten yang gagal. Secara default, APIG Ingress tidak mencoba ulang permintaan POST atau PATCH non-idempoten yang gagal. Jika Anda mengonfigurasi non_idempotent, aktifkan percobaan ulang. off: Nonaktifkan percobaan ulang.

Contohnya, atur jumlah maksimum percobaan ulang untuk permintaan example/test menjadi 2, timeout percobaan ulang menjadi 5 detik, coba ulang hanya untuk kode status HTTP 502, dan aktifkan percobaan ulang non-idempoten. Konfigurasikan sebagai berikut:

Kluster untuk Kubernetes 1.19 dan yang 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: apig
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /test
            pathType: Exact

Kluster untuk Kubernetes Sebelum 1.19

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: apig
  rules:
    - host: example.com 
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

Kontrol Akses Daftar Hitam dan Daftar Putih IP

APIG Ingress mendukung kontrol akses daftar hitam dan daftar putih IP pada tingkat domain dan route. Kontrol akses tingkat route memiliki prioritas lebih tinggi daripada kontrol akses tingkat domain.

Kontrol akses IP tingkat route

Anotasi	Deskripsi
nginx.ingress.kubernetes.io/whitelist-source-range	Menentukan daftar putih IP untuk suatu route. Mendukung alamat IP atau Blok CIDR (Classless Inter-Domain Routing). Pisahkan beberapa entri dengan koma.
higress.ingress.kubernetes.io/blacklist-source-range	Menentukan daftar hitam IP untuk suatu route. Mendukung alamat IP atau Blok CIDR. Pisahkan beberapa entri dengan koma.

Contohnya:

Untuk mengizinkan akses ke example.com/test hanya dari alamat IP klien 1.1.X.X, gunakan konfigurasi berikut:

Kluster versi 1.19 dan yang 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: apig
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /test
            pathType: Exact

Kluster sebelum versi 1.19

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

Untuk menolak akses ke example.com/test dari alamat IP klien 2.2.2.2, gunakan konfigurasi berikut:

Kluster versi 1.19 dan yang lebih baru

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

Kluster sebelum versi 1.19

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

Kontrol akses IP tingkat domain

Anotasi	Deskripsi
higress.ingress.kubernetes.io/domain-whitelist-source-range	Menentukan daftar putih IP untuk nama domain. Pengaturan tingkat domain memiliki prioritas lebih rendah daripada pengaturan tingkat route. Mendukung alamat IP atau Blok CIDR. Pisahkan alamat IP dengan koma.
higress.ingress.kubernetes.io/domain-blacklist-source-range	Menentukan daftar hitam IP untuk nama domain. Pengaturan tingkat domain memiliki prioritas lebih rendah daripada pengaturan tingkat route. Mendukung alamat IP atau Blok CIDR. Pisahkan alamat IP dengan koma.

Contohnya:

Untuk mengizinkan akses ke semua route di bawah nama domain example.com hanya dari alamat IP klien 1.1.X.X dan 2.2.2.2, gunakan konfigurasi berikut:

Kluster versi 1.19 dan yang lebih baru

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.ingress.kubernetes.io/domain-whitelist-source-range: 1.1.X.X,2.2.2.2
  name: demo
spec:
  ingressClassName: apig
  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

Kluster sebelum versi 1.19

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

Gabungkan kontrol akses IP tingkat domain dan tingkat route. Contohnya, untuk mengizinkan permintaan dari alamat IP klien 1.1.X.X dan 2.2.2.2 mengakses semua route di bawah domain example.com, tetapi hanya mengizinkan permintaan dari alamat IP klien 3.3.X.X mengakses route example.com/order, gunakan konfigurasi berikut:

Kluster versi 1.19 dan yang lebih baru

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.ingress.kubernetes.io/domain-whitelist-source-range: 1.1.X.X,2.2.2.2
  name: demo-domain
spec:
  ingressClassName: apig
  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: apig
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /order
            pathType: Exact

Kluster sebelum versi 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    higress.ingress.kubernetes.io/domain-whitelist-source-range: 1.1.X.X,2.2.2.2
  name: demo-domain
spec:
  ingressClassName: apig
  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: apig
  rules:
    - host: example.com
      http:
        paths:
          - path: /order
            backend:
              serviceName: demo-service
              servicePort: 80

Pembatasan Laju per Instans

APIG Ingress mendukung pembatasan laju per instans pada tingkat routing. Selama periode tertentu, ini membatasi jumlah permintaan yang cocok dengan route tertentu pada setiap replika gateway hingga tidak melebihi ambang batas yang dikonfigurasi.

Catatan

Pembatasan laju ini berlaku per instans. Ambang batas yang dikonfigurasi diberlakukan secara terpisah pada setiap instans gateway. Untuk membatasi trafik untuk suatu route di seluruh kluster gateway, gunakan pembatasan laju global.

Anotasi	Deskripsi
higress.ingress.kubernetes.io/route-limit-rpm	Jumlah maksimum permintaan per menit untuk route ini pada setiap instans gateway. Jumlah maksimum permintaan burst sama dengan nilai ini dikalikan dengan limit-burst-multiplier. Ketika pembatasan laju dipicu, badan respons berisi `local_rate_limited`. Kode status respons tergantung pada versi gateway: Versi gateway sebelum 1.2.23: kode status 503. Versi gateway 1.2.23 atau yang lebih baru: kode status 429.
higress.ingress.kubernetes.io/route-limit-rps	Jumlah maksimum permintaan per detik untuk route ini pada setiap instans gateway. Jumlah maksimum permintaan burst sama dengan nilai ini dikalikan dengan limit-burst-multiplier. Ketika pembatasan laju dipicu, badan respons berisi `local_rate_limited`, dan kode status respons adalah sebagai berikut: Versi gateway sebelum 1.2.23: kode status 503. Versi gateway 1.2.23 atau yang lebih baru: kode status 429.
higress.ingress.kubernetes.io/route-limit-burst-multiplier	Pengali burst untuk jumlah maksimum permintaan burst. Nilai default adalah 5.

Contoh:

Batasi permintaan ke example.com/test hingga 100 per menit, dengan kapasitas burst 200. Konfigurasikan sebagai berikut:

Kluster menjalankan Kubernetes 1.19 atau yang lebih baru

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

Kluster menjalankan Kubernetes sebelum 1.19

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

Batasi permintaan ke example.com/test hingga 10 per detik, dengan kapasitas burst 50. Konfigurasikan sebagai berikut:

Kluster menjalankan Kubernetes 1.19 atau yang lebih baru

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    higress.ingress.kubernetes.io/route-limit-rps: "10"
    # Default is 5
    # higress.ingress.kubernetes.io/route-limit-burst-multiplier: "5"
  name: demo
spec:
  ingressClassName: apig
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /test
            pathType: Exact

Kluster menjalankan Kubernetes sebelum 1.19

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

Kontrol Pembatasan Laju Global

APIG Ingress terintegrasi dengan Sentinel untuk menyediakan pembatasan laju global tingkat route untuk kluster gateway. Fitur ini membatasi jumlah maksimum permintaan per detik untuk suatu route di seluruh kluster.

Catatan

Fitur ini memerlukan versi gateway APIG Ingress 1.2.25 atau yang lebih baru.

Anda dapat menggunakan anotasi higress.ingress.kubernetes.io/rate-limit untuk mengatur jumlah maksimum permintaan per detik untuk suatu route di seluruh kluster gateway. Ketika pembatasan laju dipicu, perilaku default adalah mengembalikan respons dengan kode status 429 dan badan respons 'sentinel rate limited'. APIG Ingress menawarkan dua cara untuk menyesuaikan perilaku ini: respons kustom dan pengalihan. Anda hanya dapat menggunakan salah satu opsi ini.

Respons kustom

higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-code: Kode status respons ketika pembatasan laju dipicu. Nilai default adalah 429.
higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type: Format badan respons ketika pembatasan laju dipicu. Nilai default adalah text.
- Ketika dikonfigurasi sebagai text, nilai Content-Type respons adalah text/plain; charset=UTF-8.
- Ketika dikonfigurasi sebagai json, nilai header Content-Type respons adalah application/json; charset=UTF-8.
higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body: Badan respons ketika pembatasan laju dipicu. Nilai default adalah sentinel rate limited.

Contoh 1: Konfigurasi berikut membatasi permintaan untuk example.com/test hingga 100 per detik di seluruh kluster gateway dan menggunakan perilaku pembatasan laju default.

Kluster versi 1.19 dan yang lebih baru

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

Kluster sebelum versi 1.19

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

Contoh 2: Konfigurasi berikut membatasi permintaan untuk example.com/test hingga 100 per detik di seluruh kluster gateway. Ketika pembatasan laju dipicu, gateway mengembalikan kode status 503 dan badan respons server is overload.

Kluster versi 1.19 dan yang lebih baru

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

Kluster sebelum versi 1.19

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

Pengalihan

higress.ingress.kubernetes.io/rate-limit-fallback-redirect-url: URL pengalihan ketika pembatasan laju dipicu.

Contoh 1: Konfigurasi berikut membatasi permintaan untuk example.com/test hingga 100 per detik di seluruh kluster gateway. Ketika pembatasan laju dipicu, permintaan dialihkan ke example.com/fallback.

Kluster versi 1.19 dan yang lebih baru

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

Kluster sebelum versi 1.19

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

Kontrol Konkurensi Global

APIG Ingress terintegrasi dengan Sentinel untuk menyediakan kontrol konkurensi global pada tingkat routing untuk kluster gateway. Ini membatasi jumlah maksimum permintaan konkuren yang dapat diproses oleh suatu route di seluruh kluster gateway.

Catatan

Fitur ini memerlukan versi gateway APIG Ingress 1.2.25 atau yang lebih baru.

Atur jumlah maksimum permintaan konkuren untuk suatu route di seluruh kluster gateway menggunakan anotasi higress.ingress.kubernetes.io/concurrency-limit. Ketika kontrol konkurensi global dipicu, kode status respons adalah 429 dan badan respons adalah sentinel rate limited. APIG Ingress mendukung dua cara untuk menyesuaikan perilaku kontrol konkurensi: respons kustom dan pengalihan. Anda hanya dapat menggunakan salah satu opsi ini.

Respons kustom

higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code: Kode status HTTP yang dikembalikan ketika kontrol konkurensi dipicu. Nilai default adalah 429.
higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type: Format badan respons ketika kontrol konkurensi dipicu. Nilai default adalah text.
- Ketika diatur ke text, Content-Type respons adalah text/plain; charset=UTF-8.
- Ketika diatur ke json, Content-Type respons adalah application/json; charset=UTF-8.
higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body: Badan respons ketika kontrol konkurensi dipicu. Nilai default adalah sentinel rate limited.

Contoh 1: Batasi jumlah maksimum permintaan konkuren untuk example.com/test hingga 1000 di seluruh kluster gateway. Gunakan perilaku kontrol konkurensi default.

Kluster menjalankan Kubernetes 1.19 atau yang lebih baru

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

Kluster menjalankan Kubernetes sebelum 1.19

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

Contoh 2: Batasi jumlah maksimum permintaan konkuren untuk example.com/test hingga 1000 di seluruh kluster gateway. Ketika kontrol konkurensi dipicu, kembalikan kode status 503 dan badan respons server is overloaded.

Kluster menjalankan Kubernetes 1.19 atau yang lebih baru

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

Kluster menjalankan Kubernetes sebelum 1.19

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

Pengalihan

higress.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url: URL untuk dialihkan ketika kontrol konkurensi dipicu.

Batasi jumlah maksimum permintaan konkuren untuk example.com/test hingga 1000 di seluruh kluster gateway. Ketika kontrol konkurensi dipicu, alihkan ke example.com/fallback.

Kluster menjalankan Kubernetes 1.19 atau yang lebih baru

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

Kluster menjalankan Kubernetes sebelum 1.19

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

Pencerminan Trafik

Konfigurasikan pencerminan trafik untuk menyalin trafik ke layanan tertentu. Ini biasanya digunakan untuk skenario audit operasi dan pengujian trafik.

higress.ingress.kubernetes.io/mirror-target-service: Menyalin trafik ke layanan mirror tertentu. Format layanan adalah namespace/name:port.
- namespace: Namespace tempat Service Kubernetes berada. Opsional. Nilai default adalah namespace tempat Ingress berada.
- name: Nama Service Kubernetes. Wajib.
- port: Port tempat trafik diteruskan pada Service Kubernetes. Opsional. Nilai default adalah port pertama.
higress.ingress.kubernetes.io/mirror-percentage: Persentase trafik yang disalin. Rentang yang dapat dikonfigurasi adalah 0 hingga 100. Nilai default adalah 100.

Catatan

Ketika trafik yang disalin diteruskan ke layanan target, Host dalam permintaan asli secara otomatis menambahkan akhiran -shadow.

Contohnya, salin dan teruskan trafik dari example.com/test ke layanan target dengan namespace test, nama layanan app, dan port 8080.

Catatan

Dalam contoh ini, ketika trafik yang disalin diteruskan ke layanan target, Host secara otomatis ditulis ulang menjadi example.com-shadow.

Kluster Menjalankan Versi 1.19 dan yang Lebih Baru

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

Kluster Menjalankan Versi Sebelum 1.19

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

Contohnya, salin dan teruskan trafik dari example.com/test ke layanan target dengan namespace test, nama layanan app, port 8080, dan persentase salinan 10%.

Catatan

Dalam contoh ini, ketika lalu lintas yang disalin diteruskan ke layanan target, Host secara otomatis ditulis ulang menjadi example.com-shadow.

Kluster Menjalankan Versi 1.19 dan yang Lebih Baru

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

Kluster Menjalankan Versi Sebelum 1.19

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

Konfigurasi protokol layanan backend: HTTPS atau gRPC

Secara default, APIG Ingress meneruskan permintaan ke kontainer aplikasi backend menggunakan protokol HTTP. Jika kontainer aplikasi Anda menggunakan protokol HTTPS, tambahkan anotasi nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" untuk meneruskan permintaan ke kontainer aplikasi backend. Jika kontainer aplikasi Anda menyediakan layanan gRPC, tambahkan anotasi nginx.ingress.kubernetes.io/backend-protocol: "GRPC" untuk meneruskan permintaan ke kontainer aplikasi backend.

Catatan

Berbeda dengan NGINX Ingress, APIG Ingress secara otomatis menggunakan gRPC atau HTTP/2 jika Nama Port dalam resource Service Kubernetes untuk layanan backend Anda didefinisikan sebagai grpc atau http2. Dalam kasus ini, Anda tidak perlu mengonfigurasi anotasi nginx.ingress.kubernetes.io/backend-protocol: "GRPC".

Contohnya:

Teruskan permintaan example/test ke layanan backend menggunakan protokol HTTPS. Gunakan konfigurasi berikut:

Kluster menjalankan Kubernetes 1.19 atau yang lebih baru

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

Kluster menjalankan versi Kubernetes sebelum 1.19

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

Teruskan permintaan example/test ke layanan backend menggunakan protokol gRPC. Anda dapat menggunakan salah satu dari dua metode berikut:

Metode 1: Gunakan anotasi. Konfigurasikan sebagai berikut:

Kluster menjalankan Kubernetes 1.19 atau yang lebih baru

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

Kluster menjalankan versi Kubernetes sebelum 1.19

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

Metode 2: Gunakan Nama Port Service. Konfigurasikan sebagai berikut:

Kluster menjalankan Kubernetes 1.19 atau yang lebih baru

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: apig
  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

Kluster menjalankan versi Kubernetes sebelum 1.19

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: apig
  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

Konfigurasi algoritma penyeimbangan beban untuk layanan backend

Penyeimbangan beban menentukan bagaimana gateway memilih node saat meneruskan permintaan ke layanan backend.

Algoritma penyeimbangan beban standar

nginx.ingress.kubernetes.io/load-balance: Algoritma penyeimbangan beban standar untuk layanan backend. Nilai default adalah round_robin. Nilai yang valid adalah:

round_robin: Penyeimbangan beban round-robin.
least_conn: Penyeimbangan beban least-connections.
random: Penyeimbangan beban acak.

Penting

Gateway cloud-native tidak mendukung algoritma EWMA. Jika Anda mengonfigurasi EWMA, gateway akan kembali ke round-robin.

Contohnya, atur algoritma penyeimbangan beban untuk layanan backend demo-service ke least_conn. Konfigurasikan sebagai berikut:

Kluster menjalankan Kubernetes 1.19 atau yang lebih baru

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

Kluster menjalankan Kubernetes sebelum 1.19

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

Algoritma penyeimbangan beban consistent-hash

Penyeimbangan beban consistent-hash memastikan afinitas permintaan. Permintaan dengan kunci hash yang sama selalu menuju node yang sama. APIG Ingress mendukung penggunaan variabel NGINX yang dipilih, header permintaan, dan parameter path permintaan sebagai kunci hash.

nginx.ingress.kubernetes.io/upstream-hash-by: Algoritma penyeimbangan beban consistent-hash. Gateway cloud-native mendukung jenis kunci hash berikut:

Gateway cloud-native mendukung variabel NGINX yang dipilih:
- $request_uri: Path yang diminta, termasuk parameter path, berfungsi sebagai kunci hash.
- $host: Gunakan header host permintaan sebagai kunci hash.
- $remote_addr: Gunakan alamat IP klien sebagai kunci hash.
Consistent-hash berdasarkan header permintaan. Atur anotasi menjadi $http_headerName.
Consistent-hash berdasarkan parameter path permintaan. Atur anotasi menjadi $arg_varName.

Contoh:

Gunakan alamat IP klien sebagai kunci hash. Permintaan dari alamat IP klien yang sama selalu menuju node yang sama. Konfigurasikan sebagai berikut:

Kluster menjalankan Kubernetes 1.19 atau yang lebih baru

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

Kluster menjalankan Kubernetes sebelum 1.19

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

Gunakan header permintaan x-stage sebagai kunci hash. Permintaan dengan nilai header x-stage yang sama selalu menuju node yang sama. Konfigurasikan sebagai berikut:

Kluster menjalankan Kubernetes 1.19 atau yang 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: apig
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /test
            pathType: Exact

Kluster menjalankan Kubernetes sebelum 1.19

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

Gunakan parameter path x-stage sebagai kunci hash. Permintaan dengan nilai parameter path x-stage yang sama selalu menuju node yang sama. Konfigurasikan sebagai berikut:

Kluster menjalankan Kubernetes 1.19 atau yang 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: apig
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /test
            pathType: Exact

Kluster menjalankan Kubernetes sebelum 1.19

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

Pemanasan Layanan (Graceful Start)

Pemanasan layanan memastikan bahwa ketika node baru online, trafik secara bertahap meningkat dalam periode ramp-up yang ditentukan. Ini menjamin bahwa node baru menyelesaikan pemanasannya.

higress.ingress.kubernetes.io/warmup: Periode ramp-up layanan, dalam detik. Dinonaktifkan secara default.

Catatan

Pemanasan layanan bergantung pada algoritma penyeimbangan beban yang dipilih. Saat ini, hanya mendukung Round Robin dan least_conn.

Contohnya, untuk mengaktifkan pemanasan untuk layanan backend demo-service dengan periode ramp-up 30 detik, konfigurasikan sebagai berikut:

Kluster menjalankan Kubernetes 1.19 atau yang lebih baru

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

Kluster menjalankan Kubernetes sebelum 1.19

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

Afinitas Cookie (Persistensi Sesi)

Permintaan dengan cookie yang sama selalu diarahkan ke node yang sama oleh gateway. Jika permintaan pertama mencakup cookie, APIG Ingress menghasilkan cookie dalam respons pertama. Cookie ini memastikan bahwa permintaan berikutnya selalu diarahkan ke node yang sama.

Anotasi	Deskripsi
nginx.ingress.kubernetes.io/affinity	Jenis afinitas. Hanya afinitas cookie yang didukung. Nilai default adalah cookie.
nginx.ingress.kubernetes.io/affinity-mode	Mode afinitas. Gateway cloud-native hanya mendukung mode Balanced. Nilai default adalah Balanced.
nginx.ingress.kubernetes.io/session-cookie-name	Menetapkan nilai cookie tertentu sebagai kunci hash, yang default-nya adalah INGRESSCOOKIE.
nginx.ingress.kubernetes.io/session-cookie-path	Nilai path untuk cookie yang dihasilkan ketika cookie yang ditentukan tidak ada. Nilai default adalah /.
nginx.ingress.kubernetes.io/session-cookie-max-age	Usia maksimum, dalam detik, cookie yang dihasilkan ketika cookie yang ditentukan tidak ada. Nilai default adalah tingkat sesi.
nginx.ingress.kubernetes.io/session-cookie-expires	Waktu kedaluwarsa, dalam detik, cookie yang dihasilkan ketika cookie yang ditentukan tidak ada. Nilai default adalah tingkat sesi.

Contoh:

Aktifkan afinitas cookie menggunakan konfigurasi APIG Ingress default. Nama cookie adalah INGRESSCOOKIE. Path cookie adalah /. Siklus hidup cookie adalah tingkat sesi. Konfigurasikan sebagai berikut:

Kluster menjalankan Kubernetes 1.19 atau yang lebih baru

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

Kluster menjalankan Kubernetes sebelum 1.19

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

Aktifkan afinitas cookie dengan nama cookie test, path cookie /, dan waktu kedaluwarsa cookie 10 detik. Konfigurasikan sebagai berikut:

Kluster menjalankan Kubernetes 1.19 atau yang 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: apig
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /test
            pathType: Exact

Kluster menjalankan Kubernetes sebelum 1.19

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: apig
  rules:
    - host: example.com
      http:
        paths:
          - path: /test
            backend:
              serviceName: demo-service
              servicePort: 80

Konfigurasi Kolam Koneksi Antara Gateway dan Layanan Backend

Konfigurasikan kolam koneksi untuk layanan tertentu pada gateway. Ini mengontrol jumlah koneksi antara gateway dan layanan backend, mencegah kelebihan beban layanan backend serta meningkatkan stabilitas dan ketersediaan tinggi layanan backend.

higress.ingress.kubernetes.io/connection-policy-tcp-max-connection: Jumlah maksimum koneksi yang dapat dibuat antara gateway dan layanan backend.
higress.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint: Jumlah maksimum koneksi yang dapat dibuat antara gateway dan satu node layanan backend.
higress.ingress.kubernetes.io/connection-policy-http-max-request-per-connection: Jumlah maksimum permintaan pada satu koneksi antara gateway dan layanan backend.

Contohnya, untuk konfigurasi layanan backend demo-service, jumlah maksimum koneksi yang dapat dibuat antara gateway dan layanan backend adalah 10, dan jumlah maksimum koneksi yang dapat dibuat antara gateway dan satu node layanan backend adalah 2.

Kluster Versi 1.19 dan yang Lebih Baru

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

Kluster Sebelum Versi 1.19

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

Konfigurasi versi TLS dan paket sandi antara klien dan gateway

Secara default, APIG Ingress menetapkan versi Transport Layer Security (TLS) minimum ke TLSv1.0 dan maksimum ke TLSv1.3. Paket sandi default adalah:

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 mengatur versi TLS minimum atau maksimum dan paket sandi untuk nama domain tertentu.

Anotasi	Deskripsi
higress.ingress.kubernetes.io/tls-min-protocol-version	Menentukan versi TLS minimum. Nilai default adalah TLSv1.0. Nilai yang valid adalah: TLSv1.0 TLSv1.1 TLSv1.2 TLSv1.3
higress.ingress.kubernetes.io/tls-max-protocol-version	Menentukan versi TLS maksimum. Nilai default adalah TLSv1.3.
nginx.ingress.kubernetes.io/ssl-cipher	Menentukan paket sandi TLS. Untuk menentukan beberapa paket, pisahkan dengan titik dua (:). Pengaturan ini hanya berlaku untuk proses jabat tangan TLS yang menggunakan versi TLS 1.0 hingga 1.2.

Contohnya, untuk nama domain example.com, atur versi TLS minimum dan maksimum ke TLSv1.2. Konfigurasinya sebagai berikut:

Kluster versi 1.19 dan yang lebih baru

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

Kluster sebelum versi 1.19

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

mTLS (Mutual TLS) antara Gateway dan Layanan Backend

Secara default, APIG Ingress menggunakan protokol HTTP untuk meneruskan permintaan ke kontainer aplikasi backend. Anda dapat menggunakan anotasi nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" untuk mengonfigurasi APIG Ingress agar menggunakan protokol HTTPS untuk mengakses layanan backend. Namun, ini adalah TLS satu arah, artinya APIG Ingress hanya memverifikasi sertifikat yang disediakan oleh layanan backend. Sertifikat layanan backend biasanya harus dikeluarkan oleh Certificate Authority (CA) tepercaya. Pola yang lebih aman adalah percaya nol, di mana gateway memverifikasi sertifikat layanan backend dan layanan backend memverifikasi sertifikat gateway. Ini dikenal sebagai mutual TLS (mTLS), di mana gateway dan layanan backend melakukan otentikasi timbal balik.

Anotasi	Deskripsi
nginx.ingress.kubernetes.io/proxy-ssl-secret	Sertifikat klien yang digunakan oleh gateway untuk otentikasi identitas oleh layanan backend. Format: secretNamespace/secretName.
nginx.ingress.kubernetes.io/proxy-ssl-name	Indikasi Nama Server (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.

Contohnya, untuk mengaktifkan mTLS antara gateway dan layanan backend, gunakan rahasia bernama gateway-cert di namespace default. Konfigurasikan sebagai berikut:

Kluster menjalankan Kubernetes 1.19 atau yang 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: apig
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /test
            pathType: Exact

Kluster menjalankan Kubernetes sebelum 1.19

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