Halaman ini diterjemahkan oleh Cloud Translation API.

Ringkasan API Google Distributed Cloud dengan air gap

Application programming interface (API) 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 berbasis XML, JSON, atau gRPC. Halaman ini membahas layanan tersebut di bagiannya masing-masing.

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.

Ringkasan Kubernetes API, di https://kubernetes.io/docs/reference/using-api/
Konsep Kubernetes API, di https://kubernetes.io/docs/reference/using-api/api-concepts/
Model Resource Kubernetes (KRM), di https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md

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 server API.

Mencantumkan semua kemungkinan cluster Kubernetes yang dapat Anda akses, karena file kubeconfig Anda mungkin memiliki beberapa konteks:

kubectl config view \
    -o jsonpath='{"Cluster name\tServer\n"}{range.clusters[*]}{.name}{"\t"}{.cluster.server}{"\n"}{end}'

Ekspor nama cluster Kubernetes yang ingin Anda ajak berinteraksi dari output sebelumnya:
```
export CLUSTER_NAME="CLUSTER_NAME"
```

Tetapkan server API yang merujuk ke nama cluster Kubernetes:

APISERVER=$(kubectl config view -o jsonpath="{.clusters[?(@.name==\"$CLUSTER_NAME\")].cluster.server}")

Buat secret untuk menyimpan token akun layanan default:

kubectl apply -n NAMESPACE -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: default-token
  annotations:
    kubernetes.io/service-account.name: default
type: kubernetes.io/service-account-token
EOF

Tunggu hingga pengontrol token mengisi secret dengan token:

while ! kubectl describe secret default-token | grep -E '^token' >/dev/null; do
  echo "waiting for token..." >&2
  sleep 1
done

Tetapkan nilai token:

TOKEN=$(kubectl get secret $(kubectl get secrets | grep default | cut -f1 -d ' ')  \
    -o jsonpath='{.data.token}' | base64 --decode)

Untuk mengakses API, gunakan token 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"

Outputnya mirip dengan hal berikut ini:

{
  "kind": "APIVersions",
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}