This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Memperluas API Kubernetes

1 - Memperluas Kubernetes API dengan Lapisan Agregasi

Lapisan agregasi memungkinkan Kubernetes untuk diperluas dengan API tambahan, selain dari yang ditawarkan oleh API inti Kubernetes.

Ikhtisar

Lapisan agregasi memungkinkan instalasi tambahan beragam API Kubernetes-style di kluster kamu. Tambahan-tambahan ini dapat berupa solusi-solusi yang sudah dibangun (prebuilt) oleh pihak ke-3 yang sudah ada, seperti service-catalog, atau API yang dibuat oleh pengguna seperti apiserver-builder, yang dapat membantu kamu memulainya.

Lapisan agregasi berjalan di dalam proses bersama dengan kube-apiserver. Hingga sebuah sumber daya ekstensi terdaftar, lapisan agregasi tidak akan melakukan apapun. Untuk mendaftarkan sebuah API, pengguna harus menambahkan sebuah objek APIService, yang "mengklaim" jalur URL di API Kubernetes. Pada titik tersebut, lapisan agregasi akan mem-proxy apapun yang dikirim ke jalur API tersebut (misalnya /apis/myextension.mycompany.io/v1/…) ke APIService yang terdaftar.

Biasanya, APIService akan diimplementasikan oleh sebuah ekstensi-apiserver di dalam sebuah Pod yang berjalan di kluster. Ekstensi-apiserver ini biasanya perlu di pasangkan dengan satu atau lebih controller apabila manajemen aktif dari sumber daya tambahan diperlukan. Sebagai hasilnya, apiserver-builder sebenarnya akan memberikan kerangka untuk keduanya. Sebagai contoh lain, ketika service-catalog diinstal, ia menyediakan ekstensi-apiserver dan controller untuk layanan-layanan yang disediakannya.

Ekstensi-apiserver harus memiliki latensi koneksi yang rendah dari dan ke kube-apiserver. Secara Khusus, permintaan pencarian diperlukan untuk bolak-balik dari kube-apiserver dalam 5 detik atau kurang. Jika implementasi kamu tidak dapat menyanggupinya, kamu harus mempertimbangkan cara mengubahnya. Untuk sekarang, menyetel feature-gate EnableAggregatedDiscoveryTimeout=false di kube-apiserver akan menonaktifkan batasan waktu tersebut. Fitur ini akan dihapus dalam rilis mendatang.

Selanjutnya

2 - Custom Resource

Custom Resource adalah ekstensi dari Kubernetes API. Laman ini mendiskusikan kapan kamu melakukan penambahan sebuah Custom Resource ke klaster Kubernetes dan kapan kamu menggunakan sebuah layanan mandiri. Laman ini mendeskripsikan dua metode untuk menambahkan Custom Resource dan bagaimana cara memilihnya.

Custom Resource

Sebuah sumber daya adalah sebuah endpoint pada Kubernetes API yang menyimpan sebuah koleksi objek API dari sebuah jenis tertentu. Sebagai contoh, sumber daya bawaan Pod mengandung sebuah koleksi objek-objek Pod.

Sebuah Custom Resource adalah sebuah ekstensi dari Kubernetes API yang tidak seharusnya tersedia pada pemasangan default Kubernetes. Namun, banyak fungsi-fungsi inti Kubernetes yang sekarang dibangun menggunakan Custom Resource, membuat Kubernetes lebih modular.

Custom Resource bisa muncul dan menghilang dalam sebuah klaster yang berjalan melalui registrasi dinamis (dynamic registration), dan admin-admin klaster bisa memperbaharui Custom Resource secara independen dari klaster itu sendiri. Ketika sebuah Custom Resource dipasang, pengguna dapat membuat dan mengakses objek-objek Custom Resource menggunakan kubectl, seperti yang mereka lakukan untuk sumber daya bawaan seperti Pod.

Controller Khusus

Dengan sendirinya, Custom Resource memungkinkan kamu untuk menyimpan dan mengambil data terstruktur. Ketika kamu menggabungkan sebuah Custom Resource dengan controller khusus, Custom Resource akan memberikan sebuah API deklaratif yang sebenarnya.

Sebuah API deklaratif memungkinkan kamu untuk mendeklarasikan atau menspesifikasikan keadaan dari sumber daya kamu dan mencoba untuk menjaga agar keadaan saat itu tersinkronisasi dengan keadaan yang diinginkan. Controller menginterpretasikan data terstruktur sebagai sebuah rekaman dari keadaan yang diinginkan pengguna, dan secara kontinu menjaga keadaan ini.

Kamu bisa men-deploy dan memperbaharui sebuah controller khusus pada sebuah klaster yang berjalan, secara independen dari siklus hidup klaster itu sendiri. Controller khusus dapat berfungsi dengan sumber daya jenis apapun, tetapi mereka sangat efektif ketika dikombinasikan dengan Custom Resource. Operator pattern mengkombinasikan Custom Resource dan controller khusus. Kamu bisa menggunakan controller khusus untuk menyandi pengetahuan domain untuk aplikasi spesifik menjadi sebuah ekstensi dari Kubernetes API.

Haruskah Custom Resource ditambahkan ke dalam klaster Kubernetes saya?

Ketika membuat sebuah API baru, pikirkan apakah kamu ingin mengagregasikan API kamu dengan API klaster Kubernetes atau membiarkan API kamu berdiri sendiri.

Pilih agregasi API jika: Pilih sebuah API yang berdiri sendiri jika:
API kamu bersifat Deklaratif. API kamu tidak cocok dengan model Deklaratif.
Kamu mau tipe baru yang dapat dibaca dan ditulis dengan kubectl. Dukungan kubectl tidak diperlukan
Kamu mau melihat tipe baru pada sebuah Kubernetes UI, seperti dasbor, bersama dengan tipe-tipe bawaan. Dukungan Kubernetes UI tidak diperlukan.
Kamu mengembangkan sebuah API baru. Kamu memiliki sebuah program yang melayani API kamu dan dapat berkerja dengan baik.
Kamu bersedia menerima pembatasan format yang Kubernetes terapkan pada jalur sumber daya API (Lihat Ikhtisar API.) Kamu perlu memiliki jalur REST spesifik agar menjadi cocok dengan REST API yang telah didefinisikan.
Sumber daya kamu secara alami mencakup hingga sebuah klaster atau sebuah namespace dari sebuah klaster. Sumber daya yang mencakup klaster atau namespace adalah sebuah ketidakcocokan; kamu perlu mengendalikan jalur sumber daya spesifik.
Kamu ingin menggunakan kembali dukungan fitur Kubernetes API. Kamu tidak membutuhkan fitur tersebut.

API Deklaratif

Dalam sebuah API Deklaratif, biasanya:

  • API kamu terdiri dari sejumlah kecil dari objek yang berukuran relatif kecil (sumber daya).
  • Objek-objek mendefinisikan pengaturan dari aplikasi atau infrastruktur.
  • Objek-objek relatif tidak sering diperbaharui.
  • Manusia sering diperlukan untuk membaca dan menulis objek-objek tersebut.
  • Operasi utama terhadap objek bersifat CRUD (creating, reading, updating, dan deleting).
  • Transaksi antar objek tidak dibutuhkan; API merepresentasikan sebuah keadaan yang diinginkan, bukan keadaan yang eksak.

API imperatif bersifat tidak deklaratif. Tanda-tanda apabila API kamu tidak deklaratif termasuk:

  • klien berkata "lakukan ini", dan kemudian mendapat sebuah respon serempak ketika selesai.
  • klien berkata "lakukan ini", dan kemudian mendapat sebuah ID operasi kembali, dan harus melakukan sebuah cek terhadap objek Operation terpisah untuk menentukan selesainya sebuah permintaan.
  • Kamu berbicara tentang Remote Procedure Call (RPC).
  • Menyimpan secara langsung sejumlah data (mis. > beberapa kB per objek, atau >1000-an objek).
  • Membutuhkan akses dengan bandwidth tinggi (10-an permintaan per detik dapat ditopang).
  • Menyimpan data pengguna (seperti gambar, PII, dll) atau data berskala besar yang diproses oleh aplikasi.
  • Operasi-operasi natural terhadap objek yang tidak bersifat CRUD.
  • API yang tidak mudah dimodelkan dengan objek.
  • Kamu memilih untuk merepresentasikan operasi tertunda dengan sebuah ID operasi atau sebuah objek operasi.

Apakah saya harus menggunakan sebuah ConfigMap atau sebuah Custom Resource?

Gunakan ConfigMap jika salah satu hal berikut berlaku:

  • Terdapat sebuah format berkas pengaturan yang sudah ada, yang terdokumentasi dengan baik seperti sebuah mysql.cnf atau pom.xml.
  • Kamu ingin menaruh seluruh berkas pengaturan kedalam sebuah key dari sebuah ConfigMap.
  • Kegunaan utama dari berkas pengaturan adalah untuk dikonsumsi sebuah program yang berjalan di dalam sebuah Pod di dalam klaster kamu untuk mengatur dirinya sendiri.
  • Konsumen dari berkas lebih suka untuk mengkonsumsi lewat berkas dalam sebuah Pod atau variabel lingkungan dalam sebuah Pod, dibandingkan melalui Kubernetes API.
  • Kamu ingin melakukan pembaharuan bergulir lewat Deployment, dll, ketika berkas diperbaharui.

Gunakan sebuah Custom Resource (CRD atau Aggregated API) jika kebanyakan dari hal berikut berlaku:

  • Kamu ingin menggunakan pustaka klien Kubernetes dan CLI untuk membuat dan memperbaharui sumber daya baru.
  • Kamu ingin dukungan tingkat tinggi dari kubectl (sebagai contoh: kubectl get my-object object-name).
  • Kamu ingin membangun sebuah otomasi baru yang mengawasi pembaharuan terhadap objek baru, dan kemudian melakukan CRUD terhadap objek lainnya, atau sebaliknya.
  • Kamu ingin menulis otomasi yang menangani pembaharuan untuk objek.
  • Kamu ingin menggunakan kesepakatan API Kubernetes seperti .spec, .status, dan .metadata.
  • Kamu ingin objek tersebut untuk menjadi sebuah abstraksi terhadap sebuah kumpulan dari sumber daya terkontrol, atau peringkasan dari sumber daya lainnya.

Menambahkan Custom Resource

Kubernetes menyediakan dua cara untuk menambahkan sumber daya ke klaster kamu:

  • CRD cukup sederhana dan bisa diciptakan tanpa pemrograman apapun.
  • Agregasi API membutuhkan pemrograman, tetapi memungkinkan kendali lebih terhadap perilaku API seperti bagaimana data disimpan dan perubahan antar versi API.

Kubernetes menyediakan kedua opsi tersebut untuk memenuhi kebutuhan pengguna berbeda, jadi tidak ada kemudahan penggunaan atau fleksibilitas yang dikompromikan.

Aggregated API adalah bawahan dari APIServer yang duduk dibelakang API server utama, yang bertindak sebagai sebuah proxy. Pengaturan ini disebut Agregasi API (AA). Untuk pengguna, yang terlihat adalah Kubernetes API yang diperluas.

CRD memungkinkan pengguna untuk membuat tipe baru sumber daya tanpa menambahkan APIserver lain. Kamu tidak perlu mengerti Agregasi API untuk menggunakan CRD.

Terlepas dari bagaimana cara mereka dipasang, sumber daya baru disebut sebagai Custom Resource untuk memisahkan mereka dari sumber daya bawaan Kubernetes (seperti Pod).

CustomResourceDefinition

Sumber daya API CustomResourceDefinition memungkinkan kamu untuk medefinisikan Custom Resource. Mendefinisikan sebuah objek CRD akan membuat sebuah Custom Resource dengan sebuah nama dan skema yang kamu spesifikasikan. Kubernetes API melayani dan menangani penyimpanan dari Custom Resource kamu.

Ini membebaskan kamu dari menulis server API kamu sendiri untuk menangani Custom Resource, tetapi sifat dasar dari implementasi menyebabkan kamu memiliki fleksibilitas yang berkurang dibanding agregasi server API).

Lihat contoh controller khusus sebagai sebuah contoh dari bagaimana cara untuk mendaftarkan sebuah Custom Resource, bekerja dengan instans dari tipe baru sumber daya kamu, dan menggunakan sebuah controller untuk menangani event.

Agregasi server API

Biasanya, tiap sumber daya di API Kubernetes membutuhkan kode yang menangani permintaan REST dan mengatur peyimpanan tetap dari objek-objek. Server Kubernetes API utama menangani sumber daya bawaan seperti Pod dan Service, dan juga menangani Custom Resource dalam sebuah cara yang umum melalui CRD.

Lapisan agregasi memungkinkan kamu untuk menyediakan implementasi khusus untuk Custom Resource dengan menulis dan men-deploy API server kamu yang berdiri sendiri. API server utama menlimpahkan permintaan kepada kamu untuk Custom Resource yang kamu tangani, membuat mereka tersedia untuk semua kliennya.

Memilih sebuah metode untuk menambahkan Custom Resource

CRD lebih mudah digunakan. Aggregated API lebih fleksibel. Pilih metode yang paling baik untuk kebutuhan kamu.

Biasanya, CRD cocok jika:

  • Kamu memiliki field yang banyak
  • Kamu menggunakan sumber daya dalam perusahaan kamu, atau sebagai bagian dari proyek open-source kecil (berlawanan dengan sebuah produk komersil)

Membandingkan kemudahan penggunaan

CRD lebih mudah dibuat dibandingkan dengan Aggregated API.

CRD Aggregated API
Tidak membutuhkan pemrograman. Pengguna dapat memilih bahasa apapun untuk sebuah controller CRD. Membutuhkan pemrograman dalam Go dan membangun binary dan image. Pengguna dapat memilih bahasa apapun untuk sebuah CRD controller.
Tidak ada servis tambahan yang dijalankan; CR ditangani oleh server API. Sebuah servis tambahan untuk menciptakan dan dapat gagal.
Todal ada dukungan berjalan ketika CRD dibuat. Perbaikan bug apapun akan dianggap sebagai bagian dari peningkatan Kubernetes Master normal. Mungkin dibutuhkan untuk secara berkala mengambil perbaikan bug dari sumber dan membangun ulang dan memeperbaharui APIserver teragregasi.
Tidak butuh untuk menangani banyak versi dari API kamu. Sebagai contoh: ketika kamu mengendalikan klien untuk sumber daya ini, kamu bisa meningkatkannya selaras dengan API. Kamu perlu menangani banyak versi dari API kamu, sebagai contoh: ketika mengembangkan sebuah ekstensi untuk dibagikan kepada dunia.

Fitur lanjutan dan fleksibilitas

Aggregated API menawarkan fitur API lebih lanjut dan kustomisasi dari fitur lain, sebagai contoh: lapisan penyimpanan.

Fitur Deskripsi CRD Aggregated API
Validation Membantu pengguna-pengguna mencegah error dan memungkinkan kamu untuk mengembangkan API kamu secara independen dari klien-klien kamu. Fitur ini sangan berguna ketika ada banyak klien yang tidak semua bisa memperbaharui secara bersamaan pada waktu yang sama. Ya. Sebagian besar validasi dapat dipesifikasikan di dalam CRD OpenAPI v3.0 validation. Validasi bentuk lainnya didukung dengan penambahan sebuah Validating Webhook. Ya, cek validasi secara arbitrer
Defaulting Lihat diatas Ya, baik melalui OpenAPI v3.0 validation default keyword (GA in 1.17), maupun melalui sebuah Mutating Webhook (meskipun tidak akan dijalankan ketika membaca dari etcd untuk objek-objek lama) Ya
Multi-versioning Memungkinkan menyajikan objek yang sama lwat dua versi API. Bisa membantu memudahkan perubahan API seperti menamai ulang field-field. Tidak terlalu penting jika kamu mengendalikan versi-versi klien kamu. Ya Ya
Custom Storage Jika kamu membutuhkan penyimpanan dengan sebuah mode performa (sebagai contoh, basis data time-series dibanding penyimpanan key-value) atau isolasi untuk keamanan (sebagau contoh, rahasia penyandian atau berkas berbeda) Tidak Ya
Custom Business Logic Melakukan cek arbitrer atau tindakan-tindakan ketika membuat, membaca, atau memperbaharui sebuah objek Ya, menggunakan Webhooks. Ya
Scale Subresource Memungkinkan sistem-sistem seperti HorizontalPodAutoscaler dan PodDisruptionBudget untuk berinteraksi dengan sumber daya baru Ya Ya
Status Subresource
  • kontrol akses yang lebih baik: pengguna menulis bagian spec, controller menulis bagian status.
  • Memungkinkan pembuatan objek bertambah pada mutasi data Custom Resource (membutuhkan spec terpisah dan bagian status pada sumber daya)
 Ya Ya
Other Subresources Menambahkan operasi selain CRUD, seperti "logs" atau "exec". Tidak Ya
strategic-merge-patch Endpoint-endpoint baru yang mendukung PATCH dengan Content-Type: application/strategic-merge-patch+json. Berguna untuk memperbaharui objek-objek yang mungkin dapat dimodifikasi baik secara lokal, dan maupun lewat server. Untuk informasi lebih lanjut, lihat "Update API Objects in Place Using kubectl patch" Tidak Ya
Protocol Buffers sumber daya baru mendukung klien-klien yang ingin menggunakan Protocol Buffer Tidak Ya
OpenAPI Schema Apakah ada sebuah skema OpenAPI (swagger) untuk tipe yang bisa secara dinamis diambil dari server? Apakah pengguna terlindungi dari kesalahan pengejaan nama-nama field dengan memastikan bahwa hanya field yang diperbolehkan yang boleh diisi? Apakah tipe-tipe diberlakukan (dengan kata lain, jangan menaruh sebuah int di dalam field string?) Ya, berdasarkan pada skema OpenAPI v3.0 validation (GA pada 1.16) Ya

Fitur Umum

Ketika kamu membuat sebuah Custom Resource, baik melalui sebuah CRD atau sebuah AA, kamu mendapat banyak fitur untuk API kamu, dibandingkan dengan mengimplementasikannya diluar platform Kubernetes.

Fitur Apa yang dilakukannya
CRUD Endpoint-endpoint baru yang mendukung operasi dasar melalui HTTP dan kubectl
Watch Endpoint-endpoint baru yang mendukung operasi Kubernetes Watch melalui HTTP
Discovery Klien seperti kubectl dan dasbor yang secara otomatis menawarkan operasi list, display, dan pembaharuan field pada sumber daya kamu.
json-patch Endpoint-endpoint baru yang mendukung PATCH dengan Content-Type: application/json-patch+json
merge-patch Endpoint-endpoint baru yang mendukung PATCH dengan Content-Type: application/merge-patch+json
HTTPS Endpoint-endpoint menggunakan HTTPS
Built-in Authentication Akses ke ekstensi yang menggunakan apiserver inti (lapisan agregasi) untuk otentikasi
Built-in Authorization Akses ke ekstensi dapat menggunakan ulang otorisasi yang digunakan oleh apiserver inti (mis. RBAC)
Finalizers Penghapusan blok dari ekstensi sumber daya hingga pembersihan eksternal terjadi.
Admission Webhooks Menentukan nilai default dan memvalidasi ekstensi sumber daya saat terjadi operasi create/update/delete apapun.
UI/CLI Display Kubectl, dasbor dapat menampilkan ekstensi sumber daya
Unset vs Empty Klien-klien dapat membedakan field-field yang tidak diisi dari field-field yang memiliki nilai nol.
Client Libraries Generation Kubernetes menyediakan pustaka klien dasar, juga alat-alat untuk membuat pustaka klien dengan tipe spesifik.
Labels and annotations Metadata umum lintas objek yang cara untuk memperbaharui sumber daya inti dan Custom Resource-nya diketahui oleh alat-alat.

Persiapan pemasangan sebuah Custom Resource

Ada beberapa poin yang harus diperhatikan sebelum menambahkan sebuah Custom Resource ke klaster kamu.

Kode pihak ketiga dan poin kegagalan baru

Saat membuat sebuah CRD tidak secara otomatis menambahkan titik-titik kegagalan baru (sebagai contoh, dengan menyebabkan kode pihak ketiga untuk berjalan di API server kamu), paket-paket (sebagai contoh, Chart) atau bundel pemasangan lain seringkali sudah termasuk CRD dan juga sebagai Deployment dari kode pihak ketiga yang mengimplementasi logika bisnis untuk sebuah Custom Resource.

Memasang sebuah APIserver teragregasi selalu melibatkan tindakan menjalankan Deployment baru.

Penyimpanan

Custom Resource mengkonsumsi ruang penyimpanan dengan cara yang sama dengan ConfigMap. Membuat terlalu banyak sumber daya mungkin akan memenuhi ruang penyimpanan server API kamu.

Server Aggregated API dapat menggunakan penyimpanan yang sama dengan server API utama, dimana peringatan yang sama berlaku.

Authentication, authorization, and auditing

CRD selalu menggunakan otentikasi, otorisasi, dan audit pencatatan yang sama sebagai sumber daya bawaan dari server API kamu.

Jika kamu menggunakan RBAC untuk otorisasi, sebagian besar role RBAC tidak akan mengizinkan akses ke sumber daya baru (kecuali role cluster-admin atau role apapun yang dibuat menggunakan aturan wildcard). Kamu akan dibutuhkan untuk secara eksplisit mengizinkan akses ke sumber daya baru. CRD dan Aggregated API seringkali dibundel dengan definisi role baru untuk tipe yang mereka tambahkan.

API server teragregasi dapat atau tidak dapat menggunakan otentikasi, otorisasi, dan pengauditan yang sama dengan server API utama.

Mengakses sebuah Custom Resource

Pustaka klien Kubernetes dapat digunakan untuk mengakses Custom Resource. Tidak semua pustaka klien mendukung Custom Resource. Pustaka klien go dan python melakukannya.

Ketika kamu menambahkan sebuah Custom Resource, kamu dapat mengaksesnya dengan menggunakan:

  • kubectl
  • Klien dinamis kubernetes.
  • Sebuah klien REST yang kamu tulis
  • Sebuah klien yang dibuat menggunakan Kubernetes client generation tools (membuat satu adalah usaha lanjutan, tetapi beberapa proyek mungkin menyajikan sebuah klien bersama dengan CRD atau AA).

Selanjutnya