Ringkasan API perangkat Google Distributed Cloud dengan air gap

Application programming interface (API) perangkat dengan air gap Google Distributed Cloud (GDC) adalah antarmuka terprogram untuk layanan platform GDC. Google membangun API bidang kontrol di atas Kubernetes, menggunakan Model Resource Kubernetes (KRM). Bidang kontrol melakukan pengelolaan resource untuk layanan seperti pembuatan, penghapusan, dan pembaruan.

Layanan tertentu memiliki API ini dan API bidang datanya sendiri, yang dapat berbasis XML, JSON, atau gRPC. Hal ini diuraikan di bagian masing-masing di halaman ini.

Tentang GDC API

Ada dua jenis GDC API: yang berbasis Kubernetes dan yang tidak. Banyak GDC API adalah ekstensi ke Kubernetes API open source. Mereka menggunakan resource kustom Kubernetes dan mengandalkan KRM. API ini, seperti Kubernetes API, adalah RESTful API berbasis HTTP, yang menerima dan menampilkan JSON sebagai default, atau dalam Protobuf. Endpoint API adalah server Kubernetes yang relevan.

API GDC berbasis non-Kubernetes lainnya, seperti API AI terlatih Vertex, memiliki endpoint sendiri. Selain mendukung HTTP, beberapa API ini juga dapat diakses oleh gRPC, framework panggilan prosedur jarak jauh open source. Untuk mengetahui informasi selengkapnya tentang API tertentu, lihat dokumentasinya di menu navigasi vertikal.

Untuk mengakses GDC API, gunakan alat CLI gdcloud atau konsol GDC.

Tentang Kubernetes API dan KRM

Karena banyak API GDC merupakan ekstensi ke Kubernetes API dan mengandalkan KRM, pemahaman tentang konsep ini akan membantu Anda memanfaatkan API GDC secara maksimal.

Kubernetes API sepenuhnya bersifat deklaratif, dan semua yang ada di Kubernetes API adalah resource yang mengikuti KRM. Klien API, baik manusia maupun mesin, bertindak atas resource tersebut, sering kali dengan operasi buat, baca, perbarui, dan hapus (CRUD). Database Kubernetes menyimpan resource dan merepresentasikan status sistem. Kubernetes terus memantau resource tersebut dan menyelaraskan status sistem yang sebenarnya dengan status yang diinginkan. Misalnya, jika Anda mengupdate resource Deployment untuk menunjukkan bahwa Anda menginginkan lima replika container, bukan empat, Kubernetes akan mendeteksi perubahan jumlah replika yang diinginkan dan membuat container tambahan.

Untuk Kubernetes API inti, Kubernetes melakukan rekonsiliasi antara keadaan yang diinginkan dan keadaan sebenarnya. Ekstensi Kubernetes API adalah resource kustom yang bukan bagian dari Kubernetes API inti. Software kustom terus memantau dan berinteraksi dengan Kubernetes API serta melakukan rekonsiliasi.

Untuk mempelajari lebih lanjut Kubernetes API dan model resource Kubernetes, baca dokumentasi resmi Kubernetes.

API global dan per zona

Resource dalam GDC yang terisolasi dari internet adalah resource zonal atau resource global. Resource zona beroperasi dalam satu zona secara independen, dan pemadaman zona dapat memengaruhi sebagian atau semua resource di zona tersebut. Resource global beroperasi dengan redundansi di beberapa zona untuk fault tolerance.

GDC air-gapped menawarkan dua tingkat API bidang pengelolaan untuk membuat dan mengelola kedua jenis resource GDC: API global dan API zona.

API global dan zonal adalah API deklaratif Kubernetes yang ditayangkan di endpoint yang berbeda, dan resource GDC ditampilkan sebagai resource kustom Kubernetes di server API. Server API global berbagi satu cluster etcd yang didistribusikan di seluruh zona untuk memberikan konsistensi yang kuat dengan fault tolerance, dengan biaya latensi yang lebih tinggi dan pengurangan kueri tulis per detik (QPS) dibandingkan dengan server API zonal. Di setiap organisasi, server API pengelolaan zonal menyediakan API zonal bagi administrator dan developer untuk mengelola resource zonal, dan server API pengelolaan global menyediakan API global untuk mengelola resource multi-zona.

Akses GDC API

Alat CLI gdcloud dan konsol GDC memanfaatkan GDC API. Google merekomendasikan agar Anda menggunakannya untuk menjelajahi GDC atau melakukan operasi satu kali. Namun, jika Anda menggunakan akses otomatis atau terprogram ke GDC, Google merekomendasikan agar Anda menggunakan GDC API secara langsung.

Dukungan HTTP dan gRPC

Sebagian besar API GDC menyediakan antarmuka HTTP JSON yang dapat Anda panggil secara langsung. API berbasis Kubernetes menggunakan library klien Kubernetes. Beberapa API GDC non-Kubernetes memiliki antarmuka gRPC, yang memberikan peningkatan performa dan kegunaan. Google juga menyediakan library klien untuk GDC API yang tidak berbasis pada Kubernetes. Untuk membaca selengkapnya tentang gRPC, buka https://grpc.io/.

Enkripsi TLS

Semua API GDC menerima permintaan menggunakan enkripsi Transport Layer Security (TLS).

  • Jika Anda menggunakan salah satu library klien Kubernetes atau GDC, library akan menangani enkripsi saat transit untuk Anda.
  • Jika Anda menggunakan klien HTTP atau gRPC sendiri, Anda harus melakukan autentikasi dengan GDC, yang memerlukan TLS. Untuk gRPC, ikuti petunjuk dalam panduan autentikasi gRPC di https://grpc.io/docs/guides/auth/.

Mengakses Kubernetes API dan API berbasis Kubernetes

CLI Kubernetes kubectl adalah cara utama untuk berinteraksi langsung dengan Kubernetes API dan API berbasis Kubernetes.

Akses dengan kubectl

Saat mengakses Kubernetes API untuk pertama kalinya, gunakan alat command line Kubernetes, kubectl.

Untuk mengakses cluster, Anda memerlukan informasi lokasi cluster dan kredensial untuk mengaksesnya. Lihat bagian Login untuk mempelajari cara mendapatkan akses ke kredensial tersebut.

Periksa konfigurasi kubectl Anda saat ini dan lihat cluster yang dapat Anda akses:

kubectl config view

Akses langsung ke API dengan klien HTTP

Berikut adalah cara untuk mengakses REST API secara langsung dengan klien HTTP seperti curl, wget, atau browser:

  • Mengandalkan kubectl untuk menangani autentikasi dengan menggunakannya dalam mode proxy.
  • Menangani autentikasi sendiri.
Jalankan kubectl proxy

Perintah kubectl proxy menjalankan kubectl dalam mode yang bertindak sebagai reverse proxy. Perintah ini terhubung ke apiserver dan mengelola autentikasi.

Menjalankan kubectl dalam mode proxy menggunakan lokasi server API yang disimpan dan memverifikasi identitas server API menggunakan sertifikat. Metode ini melindungi dari serangan man-in-the-middle (MITM).

Contoh berikut menunjukkan cara menggunakan perintah kubectl proxy:

kubectl proxy --port=8080 &

Setelah proxy kubectl berjalan, Anda dapat menjelajahi API dengan curl, wget, atau browser, seperti yang ditunjukkan berikut:

$ curl http://localhost:8080/api/
{
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}
Menjalankan tanpa proxy kubectl

Jika tidak ingin menjalankan kubectl dalam mode proxy, Anda dapat meneruskan token autentikasi langsung ke apiserver. Ganti [YOUR_CLUSTER] dengan nama cluster yang ingin Anda ajak berinteraksi dalam perintah berikut:

# Check all possible clusters, as your kubeconfig file may have multiple contexts:
kubectl config view \
    -o jsonpath='{"Cluster name\tServer\n"}{range.clusters[*]}{.name}{"\t"}{.cluster.server}{"\n"}{end}'
# Select name of cluster you want to interact with from the previous output:
export CLUSTER_NAME="[YOUR_CLUSTER]"
APISERVER=$(kubectl config view -o jsonpath="{.clusters[?(@.name==\"$CLUSTER_NAME\")].cluster.server}")
TOKEN=$(kubectl get secret $(kubectl get secrets | grep default | cut -f1 -d ' ')  \
    -o jsonpath='{.data.token}' | base64 --decode)

Setelah mengekspor token dalam variabel lingkungan $TOKEN, gunakan dengan alat seperti curl dengan menambahkan header HTTP Authorization: Bearer $TOKEN seperti yang ditunjukkan dalam contoh berikut:

$ curl -k $APISERVER/api --header "Authorization: Bearer $TOKEN"
{
  "kind": "APIVersions",
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}