API Kubernetes

Secara keseluruhan standar yang digunakan untuk API dijelaskan di dalam dokumentasi API standar.

Endpoints API, resource types serta contoh penggunaan dijelaskan di dalam API Reference.

Akses remote penggunaan API dijelaskan di dalam dokumentasi akses API.

API Kubernetes juga berperan sebagai skema konfigurasi yang deklaratif di dalam sistem.. Sementara itu, kubectl merupakan command-line yang dapat digunakan untuk membuat, menmperbaharui, menghapus, dan mendapatkan obyek API.

Kubernetes menyimpan bentuk terserialisasi dari obyek API yang dimilikinya di dalam etcd.

Kubernetes sendiri dibagi menjadi beberapa komponen yang saling dapat saling interaksi melalui API.

Perubahan API

Berdasarkan pengalaman kami, semua sistem yang berhasil memerlukan kebutuhan untuk terus tumbuh dan berkembang seiring dengan bertambahnya kebutuhan yang ada. Dengan demikian, kami berekspektasi bahwa API akan selalu berubah seiring dengan bertambahnya kebutuhan yang ada. Meski begitu, perubahan yang ada akan selalu kompatibel dengan implementasi sebelumnya, untuk jangka waktu tertentu. Secara umum, penambahan pada sebuah resource API atau field resource bisa sering terjadi.. Penghapusan resource API atau suatu field, di sisi lain, diharapkan untuk dapat memenuhi kaidah deprecation API.

Hal-hal apa saja yang perlu diperhatikan untuk menjamin kompatibilitas API secara rinci dibahas di dalam dokumentasi perubahan API.

Swagger and OpenAPI Definition

Detail mengenai API didokumentasikan dengan menggunakan OpenAPI.

Semenjak Kubernetes versi 1.10, Kubernetes menghadirkan spesifikasi OpenAPI melalui endpoint /openapi/v2. Format request dapat diterapkan dengan cara menambahkan header HTTP:

Sebelum versi 1.14, terdapat 4 buah endpoint yang menyediakan spesifikasi OpenAPI dalam format berbeda yang dapat digunakan (/swagger.json, /swagger-2.0.0.json, /swagger-2.0.0.pb-v1, /swagger-2.0.0.pb-v1.gz). Endpoint ini bersifat deprecated dan akan dihapus pada Kubernetes versi 1.14.

Cara mendapatkan spesifikasi OpenAPI:

Kubernetes juga menyediakan alternatif mekanisme serialisasi lain, yaitu dengan menggunakan Protobuf, yang secara umum digunakan untuk mekanisme komunikasi intra-klaster, hal ini didokumentasikan di dalam proposal desain serta berkas IDL sebagai bentuk spesifikasi skema berada dalam package Go

Sebelum Kubernetes versi 1.14, apiserver Kubernetes juga mengekspos API yang dapat digunakan untuk mendapatkan spesifikasi Swagger v1.2 pada endpoint /swaggerapi. Endpoint ini akan sudah bersifat deprecated dan akan dihapus pada Kubernetes versi 1.14.

Pemberian Versi pada API

Untuk memudahkan restrukturisasi field dan resource yang ada, Kubernetes menyediakan beberapa versi API yang berada pada path yang berbeda, misalnya /api/v1 atau /apis/extensions/v1beta1.

Kita dapat memilih versi yang akan digunakan pada tingkatan API dan bukan pada tingkatan field atau resource untuk memastikan API yang digunakan memperlihatkan gambaran yang jelas serta konsisten mengenai resoure dan sifat sistem yang ada.

Perhatikan bahwa pemberian versi pada API dan pemberian versi pada API dan perangkat lunak memiliki keterkaitan secara tak langsung. Proposal API and release versioning memberikan deskripsi keterkaitan antara pemberian versi pada API dan pemberian versi pada perangkat lunak.

API dengan versi yang berbeda menunjukan tingkatan kestabilan dan ketersediaan yang diberikan pada versi tersebut. Kriteria untuk setiap tingkatan dideskripsikan secara lebih detail di dalam dokumentasi perubahan API. They are summarized here:

• Tingkatan Alpha:
  • Nama dari versi ini mengandung string alpha (misalnya, v1alpha1).
  • Bisa jadi terdapat bug. Secara default fitur ini tidak diekspos.
  • Ketersediaan untuk fitur yang ada bisa saja dihilangkan pada suatu waktu tanpa pemberitahuan sebelumnya.
  • API yang ada mungkin saja berubah tanpa memperhatikan kompatibilitas dengan versi perangkat lunak sebelumnya.
  • Hanya direkomendasikan untuk klaster yang digunakan untuk tujuan testing.
• Tingkatan Beta:
  • Nama dari versi ini mengandung string beta (misalnya v2beta3).
  • Kode yang ada sudah melalui mekanisme testing yang cukup baik. Menggunakan fitur ini dianggap cukup aman. Fitur ini diekspos secara default.
  • Ketersediaan untuk fitur secara menyeluruh tidak akan dihapus, meskipun begitu detail untuk suatu fitur bisa saja berubah.
  • Skema dan/atau semantik dari suatu obyek mungkin saja berubah tanpa memerhatikan kompatibilitas pada rilis beta selanjutnya. Jika hal ini terjadi, kami akan menyediakan suatu instruksi untuk melakukan migrasi di versi rilis selanjutnya. hal ini bisa saja terdiri dari penghapusan, pengubahan, ataupun pembuatan obyek API. Proses pengubahan mungkin saja membutuhkan pemikiran yang matang. Dampak proses ini bisa saja menyebabkan downtime aplikasi yang bergantung pada fitur ini.
  • Disarankan hanya untuk digunakan untuk penggunaan yang untuk penggunaan yang tidak berdampak langsung pada bisnis kamu.
  • Kami mohon untuk mencoba versi beta yang kami sediakan dan berikan masukan terhadap fitur yang kamu pakai! Apabila fitur tersebut sudah tidak lagi berada di dalam tingkatan beta perubahan yang kami buat terhadap fitur tersebut bisa jadi tidak lagi dapat digunakan
• Tingkatan stabil:
  • Nama dari versi ini mengandung string vX dimana X merupakan bilangan bulat.
  • Fitur yang ada pada tingkatan ini akan selalu muncul di rilis berikutnya.

API groups

Untuk memudahkan proses ekstensi suatu API Kubernetes, kami mengimplementasikan API groups. API group ini dispesifikasikan di dalam path REST serta di dalam field apiVersion dari sebuah obyek yang sudah diserialisasi.

Saat ini, terdapat beberapa API groups yang digunakan:

1. Kelompok core, seringkali disebut sebagai legacy group, berada pada path REST /api/v1 serta menggunakan apiVersion: v1.

2. Named groups berada pada path REST /apis/$GROUP_NAME/$VERSION, serta menggunakan apiVersion: $GROUP_NAME/$VERSION (misalnya apiVersion: batch/v1). Daftar menyeluruh mengenai apa saja API groups dapat dilihat di Kubernetes API reference.

Ekstensi API dengan custom resources dapat dilakukan melalui dua buah path:

1. CustomResourceDefinition digunakan jika memerlukan seluruh set semantik Kubernetes API, pengguna boleh implementasi apiserver sendiri dengan menggunakan aggregator.
2. Pengguna yang membutuhkan seperangkat semantik API Kubernetes API dapat mengimplementasikan apiserver mereka sendiri. dengan menggunakan aggregator untuk membuat integrasi dengan klien menjadi lebih mudah.

Mengaktifkan API groups

Beberapa resources dan API groups sudah diaktifkan secara default. Resource dan API groups ini dapat diaktifkan dan dinonaktifkan dengan mengatur penanda --runtime-config pada apiserver. --runtime-config menerima nilai yang dipisahkan oleh koma. Sebagai contoh: untuk menonaktifkan batch/v1, tetapkan --runtime-config=batch/v1=false, untuk mengaktifkan batch/v2alpha1, tetapkan --runtime-config=batch/v2alpha1. Penanda menerima nilai yang dipisahkan oleh pasangan key=value yang mendeskripsikan konfigurasi runtime pada apiserver.

PENTING: Melakukan proses mengaktifkan atau menonaktifkan groups atau resources membutuhkan mekanisme restart apiserver dan controller-manager agar apiserver dapat menerima perubahan --runtime-config.

Mengaktifkan resources di dalam groups

DaemonSets, Deployments, HorizontalPodAutoscalers, Ingresses, Jobs, dan ReplicaSets diaktifkan secara default. Ekstensi lain dapat diaktifkan penanda --runtime-config pada apiserver. Penanda --runtime-config menerima nilai yang dipisahkan oleh koma. Sebagai contoh untuk menonaktifkan deployments dan ingress, tetapkan. --runtime-config=extensions/v1beta1/deployments=false,extensions/v1beta1/ingresses=false