Container Service for Kubernetes:Konfigurasi fitur NGINX Ingress tingkat lanjut

Prasyarat

Pastikan hal-hal berikut:

• Kluster ACK yang dikelola telah dibuat.

• NGINX Ingress controller telah diinstal dan berjalan.

• kubectl terhubung ke kluster.

• Sebuah Deployment dan Service telah disebarkan di kluster.

Metode konfigurasi NGINX

NGINX Ingress controller di ACK sepenuhnya kompatibel dengan versi open source upstream. Tersedia tiga metode:

Konfigurasi pengalihan URL

Secara default, NGINX Ingress controller meneruskan permintaan menggunakan path lengkap. Jika path backend Anda berbeda, gunakan anotasi nginx.ingress.kubernetes.io/rewrite-target untuk menulis ulang path tersebut.

NGINX Ingress controller versi 0.22.0 dan yang lebih baru memerlukan ekspresi reguler dengan grup tangkapan (capture groups) pada path, yang digunakan bersama anotasi rewrite-target.

Terapkan templat sesuai versi Kubernetes kluster Anda.

Kubernetes 1.19 dan yang lebih baru

cat <<-EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: foo.bar.com
  namespace: default
  annotations:
    # Menulis ulang path permintaan: menghapus awalan /svc dan meneruskan sisa path ke backend.
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - path: /svc(/|$)(.*)
        backend:
          service:
            name: web1-service
            port:
              number: 80
        pathType: ImplementationSpecific
EOF

Kubernetes 1.19 atau yang lebih lama

cat <<-EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: foo.bar.com
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - path: /svc(/|$)(.*)
        backend:
          serviceName: web1-service
          servicePort: 80
EOF

Verify the configuration:

1. Dapatkan alamat IP Ingress.

   kubectl get ingress

   Output yang diharapkan:

   NAME           CLASS   HOSTS         ADDRESS        PORTS   AGE
   foo.bar.com    nginx   foo.bar.com   172.16.XX.XX   80      46m

2. Kirim permintaan menggunakan alamat IP Ingress dari kolom ADDRESS.

   curl -k -H "Host: foo.bar.com" http://<ADDRESS>/svc/foo

   Output yang diharapkan:

   web1: /foo

   Awalan /svc dihapus, sehingga backend menerima /foo.

Konfigurasi aturan penulisan ulang

Anotasi nginx.ingress.kubernetes.io/rewrite-target menangani penulisan ulang path dasar. Untuk penulisan ulang tingkat lanjut, gunakan anotasi snippet untuk menyisipkan konfigurasi NGINX kustom secara langsung:

Contoh:

annotations:
  nginx.ingress.kubernetes.io/server-snippet: |
    rewrite ^/v4/(.*)/card/query http://foo.bar.com/v5/#!/card/query permanent;
  nginx.ingress.kubernetes.io/configuration-snippet: |
    rewrite ^/v6/(.*)/card/query http://foo.bar.com/v7/#!/card/query permanent;

Verifikasi snippet dalam file nginx.conf yang dihasilkan:

kubectl exec nginx-ingress-controller-xxxxx --namespace kube-system -- cat /etc/nginx/nginx.conf
# Ganti xxxxx dengan nama pod yang sebenarnya.

server-snippet muncul di blok server {} dan configuration-snippet di blok location {}:

# start server foo.bar.com
server {
    server_name foo.bar.com;
    listen 80;
    listen [::]:80;
    set $proxy_upstream_name "-";
    # server-snippet
    rewrite ^/v4/(.*)/card/query http://foo.bar.com/v5/#!/card/query permanent;
    ...
    # configuration-snippet
    rewrite ^/v6/(.*)/card/query http://foo.bar.com/v7/#!/card/query permanent;
    ...
}
# end server foo.bar.com

Konfigurasikan snippet global dengan server-snippet di ConfigMap. Lihat dokumentasi modul rewrite NGINX untuk sintaks lengkap rewrite.

Konfigurasi sertifikat TLS untuk Ingress

Lampirkan sertifikat TLS ke Ingress untuk mengaktifkan HTTPS.

Nama domain sertifikat TLS harus sesuai dengan nilai host pada Ingress. Ketidaksesuaian akan mencegah controller memuat sertifikat tersebut.

Langkah 1: Buat sertifikat dan Secret.

1. Hasilkan sertifikat tanda tangan sendiri dan kunci privat.

   openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
     -keyout tls.key -out tls.crt \
     -subj "/CN=foo.bar.com/O=foo.bar.com"

2. Simpan sertifikat dan kunci dalam Secret Kubernetes.

   kubectl create secret tls tls-test-ingress --key tls.key --cert tls.crt

Langkah 2: Buat Ingress yang mereferensikan Secret tersebut.

Kubernetes 1.19 dan yang lebih baru

cat <<EOF | kubectl create -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: test-test-ingress
spec:
  tls:
  - hosts:
    - foo.bar.com
    secretName: tls-test-ingress  # Referensikan Secret yang dibuat di atas.
  rules:
  - host: tls-test-ingress.com
    http:
      paths:
      - path: /foo
        backend:
          service:
            name: web1-svc
            port:
              number: 80
        pathType: ImplementationSpecific
EOF

Kubernetes 1.19 atau yang lebih lama

cat <<EOF | kubectl create -f -
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: test-test-ingress
spec:
  tls:
  - hosts:
    - foo.bar.com
    secretName: tls-test-ingress
  rules:
  - host: tls-test-ingress.com
    http:
      paths:
      - path: /foo
        backend:
          serviceName: web1-svc
          servicePort: 80
EOF

Perbarui file hosts atau DNS Anda agar tls-test-ingress.com di-resolve ke alamat IP Ingress. Akses layanan melalui https://tls-test-ingress.com/foo.

Konfigurasi otentikasi TLS timbal balik

mTLS mengharuskan server dan klien sama-sama menyerahkan sertifikat selama proses jabat tangan TLS.

mTLS diterapkan per host — pengaturan yang berbeda tidak dapat diberlakukan untuk path berbeda di bawah host yang sama.

Empat anotasi mengontrol mTLS:

Langkah 1: Buat otoritas sertifikat (CA) tanda tangan sendiri.

openssl req -x509 -sha256 -newkey rsa:4096 \
  -keyout ca.key -out ca.crt \
  -days 356 -nodes \
  -subj '/CN=Fern Cert Authority'

Output yang diharapkan:

Generating a 4096 bit RSA private key
...
writing new private key to 'ca.key'

Langkah 2: Buat sertifikat server.

1. Hasilkan permintaan penandatanganan sertifikat (CSR).

   openssl req -new -newkey rsa:4096 \
     -keyout server.key -out server.csr \
     -nodes -subj '/CN=foo.bar.com'

2. Tandatangani CSR dengan CA untuk menghasilkan sertifikat server.

   openssl x509 -req -sha256 -days 365 \
     -in server.csr -CA ca.crt -CAkey ca.key \
     -set_serial 01 -out server.crt

   Output yang diharapkan:

   Signature ok
   subject=/CN=foo.bar.com
   Getting CA Private Key

Langkah 3: Buat sertifikat klien.

1. Hasilkan CSR klien.

   openssl req -new -newkey rsa:4096 \
     -keyout client.key -out client.csr \
     -nodes -subj '/CN=Fern'

2. Tandatangani CSR klien dengan CA.

   openssl x509 -req -sha256 -days 365 \
     -in client.csr -CA ca.crt -CAkey ca.key \
     -set_serial 02 -out client.crt

   Output yang diharapkan:

   Signature ok
   subject=/CN=Fern
   Getting CA Private Key

Langkah 4: Pastikan semua file sertifikat tersedia.

ls

Output yang diharapkan:

ca.crt  ca.key  client.crt  client.csr  client.key  server.crt  server.csr  server.key

Langkah 5: Buat Secret untuk sertifikat CA dan server.

kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt
kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key

Langkah 6: Buat NGINX Ingress dengan anotasi mTLS.

Kubernetes 1.19 dan yang lebih baru

cat <<-EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
    nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret"
    nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
    nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
  name: nginx-test
  namespace: default
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - backend:
          service:
            name: http-svc
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
  tls:
  - hosts:
    - foo.bar.com
    secretName: tls-secret
EOF

Kubernetes 1.19 atau yang lebih lama

cat <<-EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
    nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret"
    nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
    nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
  name: nginx-test
  namespace: default
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - backend:
          serviceName: http-svc
          servicePort: 80
        path: /
  tls:
  - hosts:
    - foo.bar.com
    secretName: tls-secret
EOF

Langkah 7: Buat atau perbarui file /etc/hosts.

Dapatkan alamat IP Ingress dan tambahkan ke file /etc/hosts.

kubectl get ing

Output yang diharapkan:

NAME         HOSTS         ADDRESS        PORTS     AGE
nginx-test   foo.bar.com   39.102.XX.XX   80, 443   4h42m

echo "39.102.XX.XX  foo.bar.com" | sudo tee -a /etc/hosts

Verify the configuration:

• Tanpa sertifikat klien — server menolak permintaan:

  curl --cacert ./ca.crt https://foo.bar.com

  Output yang diharapkan:

  <html>
  <head><title>400 No required SSL certificate was sent</title></head>
  <body>
  <center><h1>400 Bad Request</h1></center>
  <center>No required SSL certificate was sent</center>
  <hr><center>nginx/1.19.0</center>
  </body>
  </html>

• Dengan sertifikat klien — permintaan berhasil:

  curl --cacert ./ca.crt --cert ./client.crt --key ./client.key https://foo.bar.com

  Output yang diharapkan: halaman selamat datang nginx default (Welcome to nginx!).

Meneruskan permintaan HTTPS ke kontainer backend

Secara default, NGINX Ingress controller meneruskan HTTP ke backend. Untuk backend HTTPS, tambahkan anotasi nginx.ingress.kubernetes.io/backend-protocol: "HTTPS".

Kubernetes 1.19 dan yang lebih baru

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: backend-https
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  tls:
  - hosts:
    - <your-host-name>
    secretName: <your-secret-cert-name>
  rules:
  - host: <your-host-name>
    http:
      paths:
      - path: /
        backend:
          service:
            name: <your-service-name>
            port:
              number: <your-service-port>
        pathType: ImplementationSpecific

Kubernetes 1.19 atau yang lebih lama

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: backend-https
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  tls:
  - hosts:
    - <your-host-name>
    secretName: <your-secret-cert-name>
  rules:
  - host: <your-host-name>
    http:
      paths:
      - path: /
        backend:
          serviceName: <your-service-name>
          servicePort: <your-service-port>

Ganti placeholder dengan nilai Anda:

Gunakan ekspresi reguler untuk nama domain

Kubernetes tidak mendukung ekspresi reguler pada bidang host Ingress secara default. Gunakan anotasi nginx.ingress.kubernetes.io/server-alias untuk menambahkan alias server berbasis regex ke nginx.conf.

Langkah 1: Buat Ingress dengan alias server berbasis regex.

Contoh ini mencocokkan hostname apa pun dalam bentuk www.<digits>.example.com dan abc.example.com.

Kubernetes 1.19 dan yang lebih baru

cat <<-EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-regex
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/server-alias: '~^www\.\d+\.example\.com$, abc.example.com'
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - path: /foo
        backend:
          service:
            name: http-svc1
            port:
              number: 80
        pathType: ImplementationSpecific
EOF

Kubernetes 1.19 atau yang lebih lama

cat <<-EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: ingress-regex
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/server-alias: '~^www\.\d+\.example\.com$, abc.example.com'
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - path: /foo
        backend:
          serviceName: http-svc1
          servicePort: 80
EOF

Langkah 2: Verifikasi bahwa alias aktif dalam nginx.conf.

1. Dapatkan nama pod NGINX Ingress controller.

   kubectl get pods -n kube-system | grep nginx-ingress-controller

   Output yang diharapkan:

   nginx-ingress-controller-77cd987c4c-c****   1/1   Running   0   1h
   nginx-ingress-controller-77cd987c4c-x****   1/1   Running   0   1h

2. Periksa konfigurasi yang dihasilkan.

   kubectl exec -n kube-system nginx-ingress-controller-77cd987c4c-c**** cat /etc/nginx/nginx.conf | grep -C3 "foo.bar.com"

   Output yang diharapkan — direktif server_name mencantumkan semua alias:

   server {
     server_name foo.bar.com abc.example.com ~^www\.\d+\.example\.com$ ;
     listen 80  ;
     listen 443  ssl http2 ;

Langkah 3: Dapatkan alamat IP Ingress.

kubectl get ing

Output yang diharapkan:

NAME            HOSTS         ADDRESS        PORTS   AGE
ingress-regex   foo.bar.com   101.37.XX.XX   80      11s

Langkah 4: Uji semua hostname yang cocok.

Ganti <IP_ADDRESS> dengan alamat dari langkah sebelumnya.

curl -H "Host: foo.bar.com" <IP_ADDRESS>/foo        # /foo
curl -H "Host: www.123.example.com" <IP_ADDRESS>/foo # /foo
curl -H "Host: www.321.example.com" <IP_ADDRESS>/foo # /foo

Tentukan nama domain wildcard

NGINX Ingress secara native mendukung nama domain wildcard. Contoh ini mencocokkan subdomain apa pun dari ingress-regex.com.

Langkah 1: Buat Ingress dengan host wildcard.

Kubernetes 1.19 dan yang lebih baru

cat <<-EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-regex
  namespace: default
spec:
  rules:
  - host: "*.ingress-regex.com"
    http:
      paths:
      - path: /foo
        backend:
          service:
            name: http-svc1
            port:
              number: 80
        pathType: ImplementationSpecific
EOF

Kubernetes 1.19 atau yang lebih lama

cat <<-EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: ingress-regex
  namespace: default
spec:
  rules:
  - host: "*.ingress-regex.com"
    http:
      paths:
      - path: /foo
        backend:
          serviceName: http-svc1
          servicePort: 80
EOF

Langkah 2: Verifikasi server_name dalam nginx.conf.

kubectl exec -n kube-system <nginx-ingress-pod-name> cat /etc/nginx/nginx.conf | grep -C3 "ingress-regex.com"

Ganti <nginx-ingress-pod-name> dengan nama pod yang sebenarnya.

Output yang diharapkan (versi controller lama):

# start server *.ingress-regex.com
server {
  server_name *.ingress-regex.com ;
  listen 80;
  listen [::]:80;
...
}
# end server *.ingress-regex.com

Output yang diharapkan (versi controller terbaru):

## start server *.ingress-regex.com
server {
  server_name ~^(?<subdomain>[\w-]+)\.ingress-regex\.com$ ;
  listen 80;
  listen [::]:80;
...
}
## end server *.ingress-regex.com

Langkah 3: Dapatkan alamat IP Ingress.

kubectl get ing

Output yang diharapkan:

NAME            HOSTS                 ADDRESS        PORTS   AGE
ingress-regex   *.ingress-regex.com   101.37.XX.XX   80      11s

Langkah 4: Uji pencocokan wildcard.

Ganti <IP_ADDRESS> dengan alamat dari langkah sebelumnya.

curl -H "Host: abc.ingress-regex.com" <IP_ADDRESS>/foo   # /foo
curl -H "Host: 123.ingress-regex.com" <IP_ADDRESS>/foo   # /foo
curl -H "Host: a1b1.ingress-regex.com" <IP_ADDRESS>/foo  # /foo

Gunakan anotasi untuk rilis canary

Rilis canary mengarahkan sebagian trafik ke versi layanan baru. Semua konfigurasi canary memerlukan anotasi nginx.ingress.kubernetes.io/canary: "true" pada Ingress canary.

Anotasi berikut mengontrol pemisahan trafik, dievaluasi berdasarkan urutan prioritas: berbasis header → berbasis cookie → berbasis bobot.

Rilis canary berbasis bobot

Mengarahkan 20% trafik ke Service canary:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"

Rilis canary berbasis header

Jika header ack bernilai always, trafik diarahkan ke canary. Jika never, canary dilewati. Nilai lainnya menggunakan fallback berbasis bobot (50%):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "50"
    nginx.ingress.kubernetes.io/canary-by-header: "ack"

Rilis canary berbasis header dengan nilai header kustom

Jika header ack bernilai alibaba, trafik diarahkan ke canary. Nilai lainnya menggunakan fallback berbasis bobot (20%):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"
    nginx.ingress.kubernetes.io/canary-by-header: "ack"
    nginx.ingress.kubernetes.io/canary-by-header-value: "alibaba"

Rilis canary berbasis cookie

Jika tidak ada aturan header yang cocok dan cookie hangzhou_region bernilai always, trafik diarahkan ke canary. Kasus lainnya menggunakan fallback berbasis bobot (20%):

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"
    nginx.ingress.kubernetes.io/canary-by-header: "ack"
    nginx.ingress.kubernetes.io/canary-by-header-value: "alibaba"
    nginx.ingress.kubernetes.io/canary-by-cookie: "hangzhou_region"

Nilai cookie harus always atau never. Nilai kustom tidak didukung.

Untuk panduan lengkap, lihat Gunakan NGINX Ingress controller untuk menerapkan rilis canary dan penyebaran biru-hijau.

Dapatkan sertifikat TLS gratis dengan cert-manager

cert-manager mengotomatiskan penyediaan dan perpanjangan sertifikat TLS melalui Let's Encrypt di Kubernetes.

YAML ini ditujukan untuk kluster ASK (Serverless Kubernetes). Untuk kluster ACK, lihat panduan instalasi cert-manager.

kubectl apply -f https://raw.githubusercontent.com/AliyunContainerService/serverless-k8s-examples/master/cert-manager/ask-cert-manager.yaml

kubectl get pods -n cert-manager

NAME                     READY   STATUS    RESTARTS   AGE
cert-manager-1           1/1     Running   0          2m11s
cert-manager-cainjector  1/1     Running   0          2m11s
cert-manager-webhook     1/1     Running   0          2m10s

cat <<EOF | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod-http01
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: <your_email_name@gmail.com>  # Ganti dengan alamat email Anda.
    privateKeySecretRef:
      name: letsencrypt-http01
    solvers:
    - http01:
        ingress:
          class: nginx
EOF

kubectl get clusterissuer

NAME                         READY   AGE
letsencrypt-prod-http01      True    17s

cat <<EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-tls
  annotations:
    kubernetes.io/ingress.class: "nginx"
    cert-manager.io/cluster-issuer: "letsencrypt-prod-http01"
spec:
  tls:
  - hosts:
    - <your_domain_name>       # Ganti dengan nama domain Anda.
    secretName: ingress-tls
  rules:
  - host: <your_domain_name>   # Ganti dengan nama domain Anda.
    http:
      paths:
      - path: /
        backend:
          service:
            name: <your_service_name>   # Ganti dengan nama Service Anda.
            port:
              number: <your_service_port>  # Ganti dengan port Service Anda.
        pathType: ImplementationSpecific
EOF

cat <<EOF | kubectl apply -f -
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: ingress-tls
  annotations:
    kubernetes.io/ingress.class: "nginx"
    cert-manager.io/cluster-issuer: "letsencrypt-prod-http01"
spec:
  tls:
  - hosts:
    - <your_domain_name>
    secretName: ingress-tls
  rules:
  - host: <your_domain_name>
    http:
      paths:
      - path: /
        backend:
          serviceName: <your_service_name>
          servicePort: <your_service_port>
EOF

kubectl get cert

NAME          READY   SECRET        AGE
ingress-tls   True    ingress-tls   52m

kubectl describe cert ingress-tls

Events:
  Type    Reason     Age    From          Message
  ----    ------     ---    ----          -------
  Normal  Requested  64s    cert-manager  Created new CertificateRequest resource "ingress-tls-xxxxx"
  Normal  Issuing    40s    cert-manager  The certificate has been successfully issued

kubectl get secret ingress-tls

NAME          TYPE                DATA   AGE
ingress-tls   kubernetes.io/tls   2      2m

Langkah selanjutnya

• Gunakan NGINX Ingress controller untuk menerapkan rilis canary dan penyebaran biru-hijau

• Kelola NGINX Ingress controller

• Referensi konfigurasi NGINX Ingress controller