diff --git a/content/id/docs/concepts/extend-kubernetes/api-extension/custom-resources.md b/content/id/docs/concepts/extend-kubernetes/api-extension/custom-resources.md new file mode 100644 index 0000000000..7599fecef7 --- /dev/null +++ b/content/id/docs/concepts/extend-kubernetes/api-extension/custom-resources.md @@ -0,0 +1,222 @@ +--- +title: Custom Resource +content_template: templates/concept +weight: 20 +--- + +{{% capture overview %}} + +_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. + +{{% /capture %}} + +{{% capture body %}} + +## _Custom Resource_ + +Sebuah sumber daya adalah sebuah *endpoint* pada [Kubernetes API](/docs/reference/using-api/api-overview/) yang menyimpan sebuah koleksi [objek API](/docs/concepts/overview/working-with-objects/kubernetes-objects/) 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](/docs/user-guide/kubectl-overview/), 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](/docs/concepts/overview/working-with-objects/kubernetes-objects/#memahami-konsep-objek-objek-yang-ada-pada-kubernetes) +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_](https://coreos.com/blog/introducing-operators.html) 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](/docs/concepts/api-extension/apiserver-aggregation/) atau membiarkan API kamu berdiri sendiri. + +| Pilih agregasi API jika: | Pilih sebuah API yang berdiri sendiri jika: | +| ---------------------------- | ---------------------------- | +| API kamu bersifat [Deklaratif](#api-deklaratif). | API kamu tidak cocok dengan model [Deklaratif](#api-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](/docs/concepts/overview/kubernetes-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](#fitur-umum). | 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. + +{{< note >}} +Gunakan sebuah [Secret](/docs/concepts/configuration/secret/) untuk data sensitif, yang serupa dengan ConfigMap tetapi lebih aman. +{{< /note >}} + +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](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) 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](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) (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](/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/) 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](#agregasi-server-api)). + +Lihat [contoh *controller* khusus](https://github.com/kubernetes/sample-controller) 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](#customresourcedefinition). + +[Lapisan agregasi](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/) 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_](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#validation). Validasi bentuk lainnya didukung dengan penambahan sebuah [_Validating Webhook_](/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook-alpha-in-1-8-beta-in-1-9). | Ya, cek validasi secara arbitrer | +| Defaulting | Lihat diatas | Ya, baik melalui [OpenAPI v3.0 _validation_](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#defaulting) `default` keyword (GA in 1.17), maupun melalui sebuah [_Mutating Webhook_](/docs/reference/access-authn-authz/admission-controllers/#mutatingadmissionwebhook) (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](/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning) | 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_](/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks). | Ya | +| Scale Subresource | Memungkinkan sistem-sistem seperti HorizontalPodAutoscaler dan PodDisruptionBudget untuk berinteraksi dengan sumber daya baru | [Ya](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#scale-subresource) | Ya | +| Status Subresource | | [Ya](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#status-subresource) | 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"](/docs/tasks/run-application/update-api-object-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](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#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](/docs/reference/using-api/client-libraries/) 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](https://github.com/kubernetes/code-generator) (membuat satu adalah usaha lanjutan, tetapi beberapa proyek mungkin menyajikan sebuah klien bersama dengan CRD atau AA). + +{{% /capture %}} + +{{% capture whatsnext %}} + +* Belajar bagaimana untuk [Memperluas Kubernetes API dengan lapisan agregasi](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/). + +* Belajar bagaimana untuk [Memperluas Kubernetes API dengan CustomResourceDefinition](/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/). + +{{% /capture %}}