Pengontrol ingress NGINX lanjutan dan konfigurasi ingress dengan add-on perutean aplikasi untuk Azure Kubernetes Service (AKS)

Perhatian

Jaringan SIG Kubernetes dan Komite Respons Keamanan mengumumkan penghentianproyek NGINX Ingress yang akan datang, dengan pemeliharaan berakhir pada Maret 2026. Tidak ada tindakan segera yang diperlukan hari ini untuk kluster AKS yang menggunakan add-on perutean aplikasi dengan NGINX. Microsoft akan memberikan dukungan resmi untuk patch keamanan penting hingga November 2026 untuk add-on sumber daya perutean aplikasi NGINX Ingress.

AKS menyelaraskan dengan Kubernetes utama dengan pindah ke Gateway API sebagai standar jangka panjang untuk ingress dan manajemen trafik L7. Sebaiknya Anda mulai merencanakan jalur migrasi berdasarkan penyiapan Anda saat ini:

Artikel ini memandu Anda tentang dua cara untuk mengonfigurasi controller ingress dan objek ingress dengan add-on routing aplikasi untuk Azure Kubernetes Service (AKS):

Prasyarat

Hubungkan ke kluster AKS Anda

Untuk menyambungkan ke kluster Kubernetes dari komputer lokal, Anda menggunakan kubectl, klien baris perintah Kubernetes. Anda dapat menginstalnya secara lokal menggunakan az aks install-cli perintah . Jika Anda menggunakan Azure Cloud Shell, kubectl sudah terpasang.

  • Konfigurasikan kubectl untuk terhubung ke kluster Kubernetes menggunakan perintah az aks get-credentials.

    az aks get-credentials --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME
    

Properti konfigurasi untuk NGINX Ingress Controller

Add-on perutean aplikasi menggunakan definisi sumber daya kustom (CRD) Kubernetes yang dipanggil NginxIngressController untuk mengonfigurasi pengontrol ingress NGINX. Anda dapat membuat lebih banyak pengontrol ingress atau memodifikasi konfigurasi yang ada.

Tabel berikut ini mencantumkan properti yang bisa Anda atur untuk mengonfigurasi NginxIngressController:

Bidang Tipe Deskripsi Diperlukan Bawaan
controllerNamePrefix string Nama sumber daya untuk Pengontrol Ingress NGINX yang dikelola. Ya nginx
customHTTPErrors array Array kode kesalahan yang akan dikirim ke backend default jika ada kesalahan. Tidak.
defaultBackendService objek Layanan untuk merutekan lalu lintas HTTP yang tidak cocok. Berisi properti berlapis: Tidak.
name string Nama layanan. Ya
namespace string Namespace layanan. Ya
defaultSSLCertificate objek Berisi sertifikat default untuk mengakses layanan backend default. Berisi properti berlapis: Tidak.
forceSSLRedirect Boolean Memaksa pengalihan HTTPS saat sertifikat diatur. Tidak. false
keyVaultURI string URI untuk rahasia Key Vault yang menyimpan sertifikat. Tidak.
secret objek Menyimpan informasi rahasia untuk sertifikat SSL default. Berisi properti berlapis: Tidak.
  name string Nama rahasia. Ya
  namespace string Namespace rahasia. Ya
httpDisabled Boolean Bendera untuk menonaktifkan lalu lintas HTTP ke pengontrol. Tidak.
ingressClassName string Nama IngressClass yang digunakan oleh pengontrol. Ya nginx.approuting.kubernetes.azure.com
loadBalancerAnnotations objek Peta anotasi untuk mengontrol perilaku layanan pengontrol ingress NGINX dengan mengatur anotasi load balancer. Tidak.
scaling objek Konfigurasi untuk menskalakan pengontrol. Berisi properti berlapis: Tidak.
maxReplicas bilangan bulat Batas atas untuk replika. Tidak. 100
minReplicas bilangan bulat Batas minimal untuk replika. Tidak. 2
threshold string Menskalakan ambang batas yang menentukan seberapa agresif untuk menskalakan. rapid menskalakan dengan cepat untuk lonjakan tiba-tiba, steady mendukung efektivitas biaya, dan balanced merupakan campuran. Tidak. balanced

Mengontrol konfigurasi pengontrol ingress NGINX default

Saat Anda mengaktifkan add-on perutean aplikasi dengan NGINX, itu membuat pengontrol ingress bernama default di app-routing-namespace yang dikonfigurasi dengan load balancer Azure yang menghadap publik. Pengontrol ingress itu menggunakan nama kelas ingress webapprouting.kubernetes.azure.com.

Anda juga dapat mengontrol apakah default mendapatkan IP publik atau internal, atau jika dibuat sama sekali saat mengaktifkan add-on.

Opsi konfigurasi yang mungkin meliputi:

  • None: Pengontrol ingress NGINX default tidak akan dibuat dan tidak akan dihapus jika sudah ada. Anda harus menghapus sumber daya kustom default NginxIngressController secara manual jika diinginkan.
  • Internal: Pengendali ingress NGINX default dibuat dengan pemuat beban internal. Setiap perubahan anotasi pada NginxIngressController sumber daya kustom untuk membuatnya eksternal ditimpa.
  • External: Pengontrol ingress NGINX default yang dibuat dengan pengendali beban eksternal. Perubahan anotasi pada NginxIngressController sumber daya kustom untuk menjadikannya internal akan tertimpa.
  • AnnotationControlled (default): Pengontrol ingress NGINX bawaan dibuat dengan sebuah load balancer eksternal. Anda dapat mengedit sumber daya kustom default NginxIngressController untuk mengonfigurasi anotasi penyeimbang beban.

Mengontrol konfigurasi pengontrol ingress default pada kluster baru

  • Aktifkan perutean aplikasi pada kluster baru menggunakan perintah az aks create dengan flag --enable-app-routing dan --app-routing-default-nginx-controller. Anda perlu mengatur <DefaultIngressControllerType> ke salah satu opsi konfigurasi yang dijelaskan dalam Mengontrol konfigurasi pengontrol ingress NGINX default.

    az aks create \
      --resource-group $RESOURCE_GROUP \
      --name $CLUSTER_NAME \
      --location $LOCATION \
      --enable-app-routing \
      --app-routing-default-nginx-controller <DefaultIngressControllerType>
    

Memperbarui konfigurasi pengontrol ingress default pada kluster yang ada

  • Perbarui konfigurasi default pengontrol ingress perutean aplikasi pada kluster yang ada menggunakan perintah az aks approuting update dengan flag --nginx. Anda perlu mengatur <DefaultIngressControllerType> ke salah satu opsi konfigurasi yang dijelaskan dalam Mengontrol konfigurasi pengontrol ingress NGINX default.

    az aks approuting update \
      --resource-group $RESOURCE_GROUP \
      --name $CLUSTER_NAME \
      --nginx <DefaultIngressControllerType>
    

Buat pengontrol ingress NGINX untuk penggunaan publik tambahan

  1. Salin manifes YAML berikut ke dalam file baru bernama nginx-public-controller.yaml dan simpan file ke komputer lokal Anda.

    apiVersion: approuting.kubernetes.azure.com/v1alpha1
    kind: NginxIngressController
    metadata:
      name: nginx-public
    spec:
      ingressClassName: nginx-public
      controllerNamePrefix: nginx-public
    
  2. Buat sumber daya pengontrol ingress NGINX menggunakan kubectl apply perintah .

    kubectl apply -f nginx-public-controller.yaml
    

    Contoh output berikut menunjukkan sumber daya yang dibuat:

    nginxingresscontroller.approuting.kubernetes.azure.com/nginx-public created
    

Membuat pengontrol ingress NGINX internal dengan alamat IP privat

  1. Salin manifes YAML berikut ke dalam file baru bernama nginx-internal-controller.yaml dan simpan file ke komputer lokal Anda.

    apiVersion: approuting.kubernetes.azure.com/v1alpha1
    kind: NginxIngressController
    metadata:
      name: nginx-internal
    spec:
      ingressClassName: nginx-internal
      controllerNamePrefix: nginx-internal
      loadBalancerAnnotations: 
        service.beta.kubernetes.io/azure-load-balancer-internal: "true"
    
  2. Buat sumber daya pengontrol ingress NGINX menggunakan kubectl apply perintah .

    kubectl apply -f nginx-internal-controller.yaml
    

    Contoh output berikut menunjukkan sumber daya yang dibuat:

    nginxingresscontroller.approuting.kubernetes.azure.com/nginx-internal created
    

Membuat pengontrol ingress NGINX dengan alamat IP statis

  1. Buat grup sumber daya Azure menggunakan az group create perintah .

    az group create --name $NETWORK_RESOURCE_GROUP --location $LOCATION
    
  2. Buat alamat IP publik statis menggunakan az network public ip create perintah .

    az network public-ip create \
      --resource-group $NETWORK_RESOURCE_GROUP \
      --name $PUBLIC_IP_NAME \
      --sku Standard \
      --allocation-method static
    

    Nota

    Jika Anda menggunakan load balancer SKU Dasar di kluster AKS Anda, gunakan Basic untuk --sku parameter saat menentukan IP publik. Hanya IP SKU Basic yang berfungsi dengan load balancer Basic SKU dan hanya IP SKU Standard yang berfungsi dengan load balancer Standard SKU.

  3. Pastikan identitas kluster yang digunakan oleh kluster AKS memiliki izin yang didelegasikan ke grup sumber daya IP publik menggunakan az role assignment create perintah .

    CLIENT_ID=$(az aks show --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --query identity.principalId -o tsv)
    RG_SCOPE=$(az group show --name $NETWORK_RESOURCE_GROUP --query id -o tsv)
    az role assignment create \
      --assignee ${CLIENT_ID} \
      --role "Network Contributor" \
      --scope ${RG_SCOPE}
    
  4. Salin manifes YAML berikut ke dalam file baru bernama nginx-staticip-controller.yaml dan simpan file ke komputer lokal Anda.

    Nota

    Anda dapat menggunakan service.beta.kubernetes.io/azure-pip-name untuk nama IP publik, atau menggunakan service.beta.kubernetes.io/azure-load-balancer-ipv4 untuk alamat IPv4 dan service.beta.kubernetes.io/azure-load-balancer-ipv6 untuk alamat IPv6, seperti yang ditunjukkan dalam contoh YAML. Penambahan anotasi service.beta.kubernetes.io/azure-pip-name memastikan pembuatan Load Balancer secara paling efisien dan sangat dianjurkan untuk menghindari kemungkinan pembatasan.

    apiVersion: approuting.kubernetes.azure.com/v1alpha1
    kind: NginxIngressController
    metadata:
      name: nginx-static
    spec:
      ingressClassName: nginx-static
      controllerNamePrefix: nginx-static
      loadBalancerAnnotations: 
        service.beta.kubernetes.io/azure-pip-name: "$PUBLIC_IP_NAME"
        service.beta.kubernetes.io/azure-load-balancer-resource-group: "$NETWORK_RESOURCE_GROUP"
    
  5. Buat sumber daya pengontrol ingress NGINX menggunakan kubectl apply perintah .

    kubectl apply -f nginx-staticip-controller.yaml
    

    Contoh output berikut menunjukkan sumber daya yang dibuat:

    nginxingresscontroller.approuting.kubernetes.azure.com/nginx-static created
    

Cek bahwa pengontrol ingress telah dibuat

  • Verifikasi status pengontrol ingress NGINX menggunakan kubectl get nginxingresscontroller perintah .

    kubectl get nginxingresscontroller --name $INGRESS_CONTROLLER_NAME
    

    Contoh output berikut menunjukkan sumber daya yang dibuat. Mungkin perlu waktu beberapa menit agar pengontrol tersedia:

    NAME           INGRESSCLASS   CONTROLLERNAMEPREFIX   AVAILABLE
    nginx-public   nginx-public   nginx                  True
    

Melihat kondisi pengontrol ingress

  • Lihat kondisi pengontrol ingress untuk memecahkan masalah apa pun menggunakan kubectl get nginxingresscontroller perintah .

    kubectl get nginxingresscontroller --name $INGRESS_CONTROLLER_NAME -o jsonpath='{range .items[*].status.conditions[*]}{.lastTransitionTime}{"\t"}{.status}{"\t"}{.type}{"\t"}{.message}{"\n"}{end}'
    

    Contoh output berikut menunjukkan kondisi pengontrol ingress yang sehat:

    2023-11-29T19:59:24Z    True    IngressClassReady       Ingress Class is up-to-date
    2023-11-29T19:59:50Z    True    Available               Controller Deployment has minimum availability and IngressClass is up-to-date
    2023-11-29T19:59:50Z    True    ControllerAvailable     Controller Deployment is available
    2023-11-29T19:59:25Z    True    Progressing             Controller Deployment has successfully progressed
    

Gunakan pengontrol masuk dalam ingress

  1. Salin manifes YAML berikut ke dalam file baru bernama ingress.yaml dan simpan file ke komputer lokal Anda.

    Nota

    Perbarui <HostName> dengan nama host DNS Anda. <IngressClassName> adalah salah satu yang Anda tentukan saat membuat NginxIngressController.

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: aks-helloworld
      namespace: hello-web-app-routing
    spec:
      ingressClassName: <IngressClassName>
      rules:
      - host: <HostName>
        http:
          paths:
          - backend:
              service:
                name: aks-helloworld
                port:
                  number: 80
            path: /
            pathType: Prefix
    
  2. Buat sumber daya kluster menggunakan kubectl apply perintah .

    kubectl apply -f ingress.yaml --namespace hello-web-app-routing
    

    Contoh output berikut menunjukkan sumber daya yang dibuat:

    ingress.networking.k8s.io/aks-helloworld created
    

Verifikasi bahwa ingress terkelola telah dibuat

  • Verifikasi bahwa ingress terkelola dibuat menggunakan perintah kubectl get ingress.

    kubectl get ingress --namespace hello-web-app-routing
    

    Output Anda harus menyerupai contoh output berikut:

    NAME             CLASS                                HOSTS               ADDRESS       PORTS     AGE
    aks-helloworld   webapprouting.kubernetes.azure.com   myapp.contoso.com   20.51.92.19   80, 443   4m
    

Menghapus pengontrol ingress

Konfigurasi per sumber daya ingress melalui anotasi

Pengontrol ingress NGINX mendukung penambahan anotasi ke objek ingress tertentu untuk menyesuaikan perilaku mereka.

Anda dapat membuat anotasi objek ingress dengan menambahkan anotasi masing-masing di metadata.annotations bidang .

Nota

Kunci dan nilai anotasi hanya dapat berupa string. Jenis lain, seperti nilai-nilai boolean atau numerik, harus dikutip. Contoh: "true", "false", "100".

Bagian berikut ini menyediakan contoh untuk konfigurasi umum. Untuk daftar lengkapnya, lihat dokumentasi anotasi ingress NGINX.

Ukuran maksimum isi kustom

Untuk NGINX, kesalahan 413 dikembalikan ke klien ketika ukuran dalam permintaan melebihi ukuran maksimum yang diizinkan dari isi permintaan klien. Untuk mengambil alih nilai default, gunakan anotasi:

nginx.ingress.kubernetes.io/proxy-body-size: 4m

Berikut adalah contoh konfigurasi ingress menggunakan anotasi ini:

Nota

Perbarui <HostName> dengan nama host DNS Anda. <IngressClassName> adalah salah satu yang Anda tentukan saat membuat NginxIngressController.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: 4m
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Batas waktu koneksi khusus

Anda dapat mengubah batas waktu yang ditunggu oleh pengontrol ingress NGINX untuk menutup koneksi dengan beban kerja Anda. Semua nilai batas waktu tidak memiliki satuan dan diukur dalam detik. Untuk mengganti batas waktu default, gunakan anotasi berikut untuk mengatur batas waktu baca proksi 120 detik yang valid:

nginx.ingress.kubernetes.io/proxy-read-timeout: "120"

Tinjau batas waktu kustom untuk opsi konfigurasi lainnya.

Berikut adalah contoh konfigurasi ingress menggunakan anotasi ini:

Nota

Perbarui <HostName> dengan nama host DNS Anda. <IngressClassName> adalah salah satu yang Anda tentukan saat membuat NginxIngressController.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Backend Protokol

Pengontrol ingress NGINX menggunakan HTTP untuk menjangkau layanan secara default. Untuk mengonfigurasi protokol backend alternatif seperti HTTPS atau GRPC, gunakan salah satu anotasi berikut:

# HTTPS annotation
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

# GRPC annotation
nginx.ingress.kubernetes.io/backend-protocol: "GRPC"

Tinjau protokol backend untuk opsi konfigurasi lainnya.

Berikut adalah contoh konfigurasi ingress menggunakan anotasi ini:

Nota

Perbarui <HostName> dengan nama host DNS Anda. <IngressClassName> adalah salah satu yang Anda tentukan saat membuat NginxIngressController.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Berbagi Sumber Daya Antar-Asal (CORS)

Untuk mengaktifkan Berbagi Sumber Daya Lintas Asal (CORS) dalam aturan Ingress, gunakan anotasi berikut:

nginx.ingress.kubernetes.io/enable-cors: "true"

Tinjau mengaktifkan CORS untuk opsi konfigurasi lainnya.

Berikut adalah contoh konfigurasi ingress menggunakan anotasi ini:

Nota

Perbarui <HostName> dengan nama host DNS Anda. <IngressClassName> adalah salah satu yang Anda tentukan saat membuat NginxIngressController.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Menonaktifkan pengalihan SSL

Pengontrol mengalihkan (308) ke HTTPS jika TLS diaktifkan untuk ingress secara default. Untuk menonaktifkan fitur ini untuk sumber daya ingress tertentu, gunakan anotasi berikut:

nginx.ingress.kubernetes.io/ssl-redirect: "false"

Tinjau penerapan HTTPS sisi server melalui pengalihan untuk opsi konfigurasi lainnya.

Berikut adalah contoh konfigurasi ingress menggunakan anotasi ini:

Nota

Perbarui <HostName> dengan nama host DNS Anda. <IngressClassName> adalah salah satu yang Anda tentukan saat membuat NginxIngressController.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Penulisan ulang URL

Dalam beberapa skenario, URL yang diekspos dalam layanan backend berbeda dari jalur yang ditentukan dalam aturan ingress. Jika tidak ada pengaturan ulang, setiap permintaan mengembalikan 404. Konfigurasi ini berguna dengan perutean berbasis jalur di mana Anda dapat melayani dua aplikasi web yang berbeda di bawah domain yang sama. Anda dapat mengatur jalur yang diharapkan oleh layanan menggunakan anotasi berikut:

nginx.ingress.kubernetes.io/rewrite-target: /$2

Berikut adalah contoh konfigurasi ingress menggunakan anotasi ini:

Nota

Perbarui <HostName> dengan nama host DNS Anda. <IngressClassName> adalah salah satu yang Anda tentukan saat membuat NginxIngressController.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - path: /app-one(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-one
            port:
              number: 80
      - path: /app-two(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-two
            port:
              number: 80

Pembaruan jalur pemeriksaan kesehatan NGINX

Jalur pemeriksaan kesehatan default untuk Azure Load Balancer yang terkait dengan pengontrol ingress NGINX harus diatur ke "/healthz". Untuk memastikan pemeriksaan kesehatan yang benar, verifikasi bahwa layanan pengontrol ingress memiliki anotasi berikut:

metadata:
  annotations:
    service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: "/healthz"

Jika Anda menggunakan Helm untuk mengelola pengontrol ingress NGINX, Anda dapat menentukan anotasi pemeriksaan kesehatan pada Azure Load Balancer di file konfigurasi dan menerapkannya saat melakukan peningkatan:

controller:
  service:
    annotations:
      service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: "/healthz"

Konfigurasi ini membantu menjaga ketersediaan layanan dan menghindari gangguan lalu lintas yang tidak terduga selama peningkatan.

Langkah selanjutnya

Pelajari cara memantau metrik pengontrol ingress-nginx yang disertakan dengan add-on perutean aplikasi menggunakan Prometheus di Grafana sebagai bagian dari analisis performa dan penggunaan aplikasi Anda.