Gateway API

Gateway API menyediakan layanan jaringan dengan menggunakan mekanisme konfigurasi yang mudah di-extend, berorientasi role, dan mengerti konsep protokol. Gateway API adalah sebuah add-on yang berisi jenis-jenis API yang menyediakan penyediaan infrastruktur dinamis dan pengaturan trafik tingkat lanjut.

Prinsip Desain

Prinsip-prinsip berikut membentuk desain dan arsitektur Gateway API:

• Berorientasi role: Gateway API dimodelkan sesuai dengan role organisasi yang bertanggung jawab untuk mengelola jaringan layanan Kubernetes:
  • Penyedia Infrastruktur: Mengelola infrastruktur yang memungkinkan beberapa klaster terisolasi untuk melayani beberapa tenant, misalnya penyedia layanan cloud.
  • Operator klaster: Mengelola klaster dan biasanya memperhatikan kebijakan, akses jaringan, izin aplikasi, dll.
  • Pengembang Aplikasi: Mengelola aplikasi yang berjalan di dalam klaster dan biasanya memperhatikan konfigurasi tingkat aplikasi dan komposisi Service.
• Portabel: Spesifikasi Gateway API didefinisikan sebagai Custom Resource dan didukung oleh banyak implementasi.
• Ekspresif: Jenis-jenis Gateway API mendukung fungsi untuk kasus penggunaan routing trafik pada umumnya, seperti pencocokan berbasis header, pembobotan trafik, dan lainnya yang sebelumnya hanya mungkin dilakukan di Ingress dengan menggunakan anotasi kustom.
• Dapat diperluas: Gateway memungkinkan sumber daya kustom untuk dihubungkan pada berbagai lapisan API. Ini memungkinkan penyesuaian yang lebih detail pada tempat yang tepat dalam struktur API.

Model Sumber Daya (Resource)

Gateway API memiliki tiga jenis API stabil:

• GatewayClass: Mendefinisikan satu set gateway dengan konfigurasi umum dan dikelola oleh pengendali yang mengimplementasikan kelas tersebut.

• Gateway: Mendefinisikan instans infrastruktur penanganan trafik, seperti penyeimbang beban (load balancer) cloud.

• HTTPRoute: Mendefinisikan aturan khusus HTTP untuk memetakan trafik dari pendengar (listener) Gateway ke representasi titik akhir (endpoint) jaringan backend. Titik akhir ini sering diwakili sebagai sebuah Service.

Gateway API diatur ke dalam berbagai jenis API yang memiliki hubungan saling ketergantungan untuk mendukung sifat berorientasi role dari organisasi. Objek Gateway dikaitkan dengan tepat satu GatewayClass; GatewayClass menggambarkan pengendali gateway yang bertanggung jawab untuk mengelola Gateway dari kelas ini. Satu atau lebih jenis rute seperti HTTPRoute, kemudian dikaitkan dengan Gateway. Sebuah Gateway dapat memfilter rute yang mungkin akan dilampirkan pada listeners-nya, membentuk model kepercayaan dua arah dengan rute.

Gambar berikut mengilustrasikan hubungan dari tiga jenis Gateway API yang stabil:

Gateway

Gateway menggambarkan sebuah instans infrastruktur penanganan trafik. Ini mendefinisikan titik akhir jaringan yang dapat digunakan untuk memproses trafik, seperti penyaringan (filter), penyeimbangan (balancing), pemisahan (splitting), dll. untuk backend seperti sebuah Service. Sebagai contoh, Gateway dapat mewakili penyeimbang beban (load balancer) cloud atau server proksi dalam klaster yang dikonfigurasikan untuk menerima trafik HTTP.

Contoh minimal dari Gateway resource:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: example-gateway
spec:
  gatewayClassName: example-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80

Dalam contoh ini, sebuah instans dari infrastruktur penanganan trafik diprogram untuk mendengarkan trafik HTTP pada port 80. Karena field addresses tidak ditentukan, sebuah alamat atau nama host ditugaskan ke Gateway oleh pengendali implementasi. Alamat ini digunakan sebagai titik akhir jaringan untuk memproses trafik titik akhir jaringan backend yang didefinisikan dalam rute.

Lihat Gateway referensi untuk definisi lengkap dari API ini.

HTTPRoute

Jenis HTTPRoute menentukan perilaku routing dari permintaan HTTP dari listener Gateway ke titik akhir jaringan backend. Untuk backend Service, implementasi dapat mewakili titik akhir jaringan backend sebagai IP Service atau Endpoints pendukung dari Service tersebut. HTTPRoute mewakili konfigurasi yang diterapkan pada implementasi Gateway yang mendasarinya. Sebagai contoh, mendefinisikan HTTPRoute baru dapat mengakibatkan pengaturan rute trafik tambahan pada penyeimbang beban cloud atau server proksi dalam klaster.

Contoh minimal dari HTTPRoute:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: example-httproute
spec:
  parentRefs:
  - name: example-gateway
  hostnames:
  - "www.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /login
    backendRefs:
    - name: example-svc
      port: 8080

Dalam contoh ini, trafik HTTP dari Gateway example-gateway dengan header Host: yang disetel ke www.example.com dan jalur permintaan yang ditentukan sebagai /login akan diarahkan ke Service example-svc pada port 8080.

Lihat referensi HTTPRoute untuk definisi lengkap dari API ini.

Aliran Permintaan (Request Flow)

Berikut adalah contoh sederhana dari trafik HTTP yang diarahkan ke sebuah Service menggunakan Gateway dan HTTPRoute:

Dalam contoh ini, aliran permintaan untuk Gateway yang diimplementasikan sebagai reverse proxy adalah:

1. Klien mulai mempersiapkan permintaan HTTP untuk URL http://www.example.com
2. Resolver DNS klien melakukan query untuk nama tujuan dan mengetahui pemetaan ke satu atau lebih alamat IP yang terkait dengan Gateway.
3. Klien mengirimkan permintaan ke alamat IP Gateway; reverse proxy menerima permintaan HTTP dan menggunakan header Host: untuk mencocokkan konfigurasi yang berasal dari Gateway dan HTTPRoute yang terlampir.
4. Secara opsional, reverse proxy dapat melakukan pencocokan header permintaan dan/atau jalur berdasarkan aturan pencocokan dari HTTPRoute.
5. Secara opsional, reverse proxy dapat memodifikasi permintaan; sebagai contoh, untuk menambah atau menghapus header, berdasarkan aturan filter dari HTTPRoute.
6. Terakhir, reverse proxy meneruskan permintaan ke satu atau lebih backend.

Kesesuaian (Conformance)

Gateway API mencakup beragam fitur dan diimplementasikan secara luas. Kombinasi ini memerlukan definisi dan pengujian kesesuaian yang jelas untuk memastikan bahwa API memberikan pengalaman yang konsisten di mana pun digunakan.

Lihat dokumentasi conformance untuk memahami rincian seperti saluran rilis (release channel), tingkat dukungan, dan menjalankan tes kesesuaian (conformance test).

Migrasi dari Ingress

Gateway API adalah penerus API Ingress tapi tidak termasuk dalam jenis Ingress. Akibatnya, konversi satu kali dari sumber daya Ingress yang ada ke sumber daya Gateway API diperlukan.

Referensi panduan migrasi ingress untuk rincian tentang migrasi sumber daya Ingress ke sumber daya Gateway API.

Selanjutnya

Alih-alih sumber daya Gateway API yang diimplementasikan secara natif oleh Kubernetes, spesifikasinya didefinisikan sebagai Custom Resource Definition yang didukung oleh berbagai implementasi. Instal CRD Gateway API atau ikuti petunjuk instalasi dari implementasi yang kamu pilih. Setelah menginstal sebuah implementasi, gunakan panduan Memulai untuk membantu kamu segera memulai bekerja dengan Gateway API.

Referensi spesifikasi API untuk rincian tambahan dari semua jenis Gateway API.