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

• Belajar bagaimana untuk Memperluas Kubernetes API dengan lapisan agregasi.

• Belajar bagaimana untuk Memperluas Kubernetes API dengan CustomResourceDefinition.