Ingress

Buat layanan jaringan HTTP (atau HTTPS) kamu tersedia menggunakan mekanisme konfigurasi yang sadar protokol, yang memahami konsep web seperti URI, hostname, path, dan lainnya. Konsep Ingress memungkinkan kamu memetakan lalu lintas ke backend yang berbeda berdasarkan aturan yang kamu definisikan melalui API Kubernetes.

FEATURE STATE: Kubernetes v1.19 [stable]

Sebuah obyek API yang mengatur akses eksternal terhadap Service yang ada di dalam klaster, biasanya dalam bentuk request HTTP.

Ingress juga menyediakan load balancing, terminasi SSL, serta name-based virtual hosting.

Catatan:

Proyek Kubernetes merekomendasikan menggunakan Gateway daripada Ingress. API Ingress telah dibekukan. Ini berarti: API Ingress tersedia secara umum (generally available), dan tunduk pada jaminan stabilitas untuk API yang tersedia sepenuhnya. API Ingress tidak lagi dikembangkan, dan tidak akan ada perubahan atau pembaruan lebih lanjut yang dilakukan padanya.

Terminologi

Untuk kejelasan, panduan ini mendefinisikan istilah-istilah berikut:

  • Node: Mesin pekerja di Kubernetes, bagian dari sebuah klaster.
  • Klaster: Sekumpulan Node yang menjalankan aplikasi terkontainerisasi yang dikelola oleh Kubernetes. Untuk contoh ini, dan dalam sebagian besar deployment Kubernetes yang umum, Node di dalam klaster tidak menjadi bagian dari jaringan klaster itu sendiri.
  • Edgerouter: Router yang menegakkan kebijakan firewall untuk klaster kamu. Ini bisa berupa gateway yang dikelola oleh cloud provider.
  • Jaringan klaster (Cluster network): Sekumpulan tautan, baik logis maupun fisik, yang memfasilitasi komunikasi di dalam klaster kamu.
  • Service: Service Kubernetes yang mengidentifikasi sekumpulan Pod menggunakan selector.

Apa itu Ingress?

Ingress mengekspos rute HTTP dan HTTPS dari luar klaster ke Service di dalam klaster. Routing lalu lintas dikendalikan oleh aturan yang didefinisikan pada resource Ingress.

Berikut adalah contoh sederhana di mana sebuah Ingress mengirimkan seluruh lalu lintasnya ke satu Service:

diagram-ingress-fanout

Gambar. Ingress Fan Out

Sebuah Ingress dapat dikonfigurasi untuk memberikan Service URL yang dapat dijangkau secara eksternal, melakukan load balance lalu lintas, melakukan terminasi SSL / TLS, dan menawarkan virtual hosting berbasis nama. Sebuah Ingress controller bertanggung jawab untuk memenuhi Ingress, biasanya dengan load balancer, meskipun ia juga dapat mengkonfigurasi edge router kamu atau frontend tambahan untuk membantu menangani permintaan.

Ingress tidak mengekspos port atau protokol arbitrer. Mengekspos service selain HTTP dan HTTPS ke internet biasanya menggunakan service dengan tipe Service.Type=NodePort atau Service.Type=LoadBalancer.

Prasyarat

Kamu harus memiliki Ingress controller untuk memenuhi Ingress. Hanya membuat resource Ingress tidak akan memberikan efek apa pun.

Kamu dapat memilih dari sejumlah Ingress controller.

Idealnya, semua Ingress controller harus sesuai dengan spesifikasi referensi. Kenyataannya, berbagai Ingress controller beroperasi sedikit berbeda.

Catatan:

Pastikan kamu meninjau dokumentasi Ingress controller pilihan kamu untuk memahami peringatan saat memilihnya.

Sumber daya Ingress

Contoh minimal sumber daya Ingress:

service/networking/minimal-ingress.yaml 
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: minimal-ingress
spec:
  ingressClassName: nginx-example
  rules:
  - http:
      paths:
      - path: /testpath
        pathType: Prefix
        backend:
          service:
            name: test
            port:
              number: 80

Sebuah Ingress memerlukan field apiVersion, kind, metadata, dan spec. Nama objek Ingress harus merupakan Nama subdomain DNS yang valid. Untuk informasi umum tentang bekerja dengan file konfigurasi, lihat mendeploy aplikasi, mengkonfigurasi container, mengelola resource. Ingress controller sering menggunakan anotasi untuk mengkonfigurasi perilaku. Tinjau dokumentasi Ingress controller pilihan kamu untuk mengetahui anotasi mana yang diharapkan dan/atau didukung.

Spesifikasi Ingress memuat semua informasi yang dibutuhkan untuk mengkonfigurasi load balancer atau proxy server. Yang terpenting, ia berisi daftar aturan yang dicocokkan dengan semua permintaan masuk. Resource Ingress hanya mendukung aturan untuk mengarahkan lalu lintas HTTP(S).

Jika ingressClassName dihilangkan, sebuah Ingress class default sebaiknya didefinisikan.

Beberapa ingress controller bekerja bahkan tanpa definisi IngressClass default. Meskipun Kamu menggunakan ingress controller yang mampu beroperasi tanpa IngressClass apa pun, proyek Kubernetes tetap merekomendasikan agar kamu mendefinisikan IngressClass default.

Aturan Ingress

Setiap aturan HTTP memuat informasi berikut:

  • Host opsional. Dalam contoh ini, tidak ada host yang ditentukan, sehingga aturan berlaku untuk semua lalu lintas HTTP masuk melalui alamat IP yang ditentukan. Jika host disediakan (misalnya, foo.bar.com), aturan berlaku untuk host tersebut.
  • Daftar path (misal, /testpath), yang masing-masing memiliki backend terkait yang didefinisikan dengan service.name dan service.port.name atau service.port.number. Baik host maupun path harus cocok dengan konten permintaan masuk sebelum load balancer mengarahkan lalu lintas ke Service yang direferensikan.
  • Backend adalah kombinasi Service dan nama port seperti dijelaskan dalam dokumen Service atau backend custom resource melalui CRD. Permintaan HTTP (dan HTTPS) ke Ingress yang cocok dengan host dan path dari aturan dikirim ke backend yang terdaftar.

Sebuah defaultBackend sering dikonfigurasi dalam Ingress controller untuk melayani setiap permintaan yang tidak cocok dengan path dalam spesifikasi.

DefaultBackend

Ingress tanpa aturan mengirimkan semua lalu lintas ke satu default backend, dan spec.defaultBackend adalah backend yang seharusnya menangani permintaan dalam kasus tersebut. defaultBackend secara konvensional merupakan opsi konfigurasi dari Ingress controller dan tidak ditentukan dalam resource Ingress kamu. Jika tidak ada .spec.rules yang ditentukan, .spec.defaultBackend harus ditentukan. Jika defaultBackend tidak diatur, penanganan permintaan yang tidak cocok dengan aturan apa pun akan diserahkan kepada ingress controller (konsultasikan dokumentasi untuk ingress controller kamu untuk mengetahui bagaimana ia menangani kasus ini).

Jika tidak ada host atau path yang cocok dengan permintaan HTTP di objek Ingress, lalu lintas dirutekan ke default backend kamu.

Resource backends

Sebuah Resource Backend adalah ObjectRef ke resource Kubernetes lain di dalam namespace yang sama dengan objek Ingress. Sebuah Resource adalah pengaturan yang saling eksklusif dengan Service, dan akan gagal divalidasi jika keduanya ditentukan. ... Penggunaan umum untuk Resource backend adalah untuk memasukkan data ke backend object storage dengan aset statis.

service/networking/ingress-resource-backend.yaml 
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-resource-backend
spec:
  defaultBackend:
    resource:
      apiGroup: k8s.example.com
      kind: StorageBucket
      name: static-assets
  rules:
    - http:
        paths:
          - path: /icons
            pathType: ImplementationSpecific
            backend:
              resource:
                apiGroup: k8s.example.com
                kind: StorageBucket
                name: icon-assets

Setelah membuat Ingress di atas, Kamu dapat melihatnya dengan perintah berikut:


kubectl describe ingress ingress-resource-backend

Name:             ingress-resource-backend
Namespace:        default
Address:
Default backend:  APIGroup: k8s.example.com, Kind: StorageBucket, Name: static-assets
Rules:
  Host        Path  Backends
  ----        ----  --------
  *
              /icons   APIGroup: k8s.example.com, Kind: StorageBucket, Name: icon-assets
Annotations:  <none>
Events:       <none>

Jenis Path (Path types)

Setiap path dalam sebuah Ingress diwajibkan memiliki jenis path yang sesuai (path type). Path yang tidak menyertakan pathType secara eksplisit akan gagal dalam validasi. Ada tiga jenis path yang didukung:

  • ImplementationSpecific: Dengan tipe path ini, pencocokan tergantung pada IngressClass. Implementasi dapat memperlakukannya sebagai pathType yang terpisah atau memperlakukannya identik dengan tipe path Prefix atau Exact.

  • Exact: Mencocokkan path URL secara persis dan sensitif terhadap huruf besar/kecil (case-sensitive).

  • Prefix: Mencocokkan berdasarkan awalan path URL yang dipisahkan oleh /. Pencocokan sensitif terhadap huruf besar/kecil dan dilakukan per elemen path. Elemen path mengacu pada daftar label di path yang dipisahkan oleh pemisah /. Sebuah permintaan dianggap cocok untuk path p jika setiap p merupakan awalan per elemen dari path p dari path permintaan.

 

Catatan:

Jika elemen terakhir dari path merupakan substring dari elemen terakhir di path permintaan, itu bukanlah kecocokan (misalnya: /foo/bar cocok dengan /foo/bar/baz, tetapi tidak cocok dengan /foo/barbaz).

Contoh Pencocokan Path

Jenis    Path(s)                        Path Permintaan Cocok? Catatan                                                 
Prefix /                            (semua path)    Ya      Mencocokkan semua permintaan.                           
Exact  /foo                        /foo          Ya      Pencocokan persis.                                       
Exact  /foo                        /bar          Tidak  Path tidak sama.                                         
Exact  /foo                        /foo/          Tidak  Exact tidak cocok dengan trailing slash.             
Exact  /foo/                        /foo          Tidak  Exact tidak cocok dengan trailing slash.             
Prefix /foo                        /foo, /foo/ Ya      Cocok dengan prefix elemen.                             
Prefix /foo/                        /foo, /foo/ Ya      Cocok dengan prefix elemen.                             
Prefix /aaa/bb                      /aaa/bbb      Tidak  /bbb bukan elemen yang diawali /bb.                 
Prefix /aaa/bbb                    /aaa/bbb      Ya      Pencocokan persis.                                       
Prefix /aaa/bbb/                    /aaa/bbb      Ya      Mengabaikan trailing slash.                           
Prefix /aaa/bbb                    /aaa/bbb/      Ya      Cocok dengan trailing slash.                           
Prefix /aaa/bbb                    /aaa/bbb/ccc  Ya      Cocok dengan subpath.                                 
Prefix /aaa/bbb                    /aaa/bbbxyz    Tidak  Bukan kecocokan prefix elemen.                           
Prefix /, /aaa                      /aaa/ccc      Ya      Cocok dengan prefix /aaa.                             
Prefix /, /aaa, /aaa/bbb            /aaa/bbb      Ya      Cocok dengan prefix /aaa/bbb.                         
Prefix /, /aaa, /aaa/bbb            /ccc          Ya      Cocok dengan prefix /.                                 
Prefix /aaa                        /ccc          Tidak  Tidak ada kecocokan, akan menggunakan default backend.
Mixed  /foo (Prefix), /foo (Exact) /foo          Ya      Memilih Exact terlebih dahulu.                         

Multiple matches

Dalam beberapa kasus, beberapa path dalam satu Ingress akan cocok dengan sebuah permintaan. Dalam situasi ini, prioritas akan diberikan pertama-tama kepada path yang paling panjang yang cocok. Jika dua path masih sama-sama cocok, prioritas akan diberikan pada path dengan tipe path exact daripada tipe path prefix.

Hostname wildcards

Host dapat berupa kecocokan tepat (misalnya “foo.bar.com”) atau wildcard (misalnya “*.foo.com”). Kecocokan tepat memerlukan bahwa header HTTP host cocok dengan field host. Kecocokan wildcard memerlukan header HTTP host sama dengan suffix dari aturan wildcard.

Host        Header Host        Cocok?                                                 
*.foo.com bar.foo.com      Cocok berdasarkan suffix yang sama                   
*.foo.com baz.bar.foo.com Tidak cocok, wildcard hanya mencakup satu label DNS
*.foo.com foo.com          Tidak cocok, wildcard hanya mencakup satu label DNS
service/networking/ingress-wildcard-host.yaml 
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-wildcard-host
spec:
  rules:
  - host: "foo.bar.com"
    http:
      paths:
      - pathType: Prefix
        path: "/bar"
        backend:
          service:
            name: service1
            port:
              number: 80
  - host: "*.foo.com"
    http:
      paths:
      - pathType: Prefix
        path: "/foo"
        backend:
          service:
            name: service2
            port:
              number: 80

Ingress class

Ingress dapat diimplementasikan oleh controller yang berbeda, seringkali dengan konfigurasi yang berbeda. Setiap Ingress sebaiknya menentukan class, yaitu referensi ke resource IngressClass yang memuat konfigurasi tambahan termasuk nama controller yang seharusnya mengimplementasikan class tersebut.

service/networking/external-lb.yaml 
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: external-lb
spec:
  controller: example.com/ingress-controller
  parameters:
    apiGroup: k8s.example.com
    kind: IngressParameters
    name: external-lb

Field .spec.parameters dari IngressClass memungkinkan kamu mereferensikan resource lain yang menyediakan konfigurasi terkait dengan IngressClass tersebut.

Jenis parameter spesifik yang digunakan tergantung pada ingress controller yang kamu tentukan di field .spec.controller dari IngressClass.

Ruang lingkup IngressClass

Tergantung pada ingress controller kamu, kamu dapat menggunakan parameter yang kamu atur di seluruh klaster, atau hanya untuk satu namespace.