Kamu sedang menampilkan dokumentasi untuk Kubernetes versi: v1.28
Kubernetes v1.28 dokumentasi sudah tidak dirawat lagi. Versi yang kamu lihat ini hanyalah snapshot statis. Untuk dokumentasi terkini, lihat versi terbaru.
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.cnfataupom.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 |
| 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.