Google Distributed Cloud mit Air Gap – Übersicht über APIs

Google Distributed Cloud (GDC) Air-Gapped-APIs (Application Programming Interfaces) sind programmatische Schnittstellen zu den GDC-Plattformdiensten. Google erstellt die APIs der Steuerungsebene auf Kubernetes und verwendet dabei das Kubernetes-Ressourcenmodell (KRM). Die Steuerungsebene führt die Ressourcenverwaltung für Dienste wie Erstellung, Löschung und Aktualisierungen durch.

Bestimmte Dienste haben diese APIs und eigene APIs der Datenebene, die auf XML, JSON oder gRPC basieren. Diese Dienste werden auf dieser Seite in den entsprechenden Abschnitten behandelt.

GDC-APIs

Es gibt zwei Arten von GDC-APIs: Kubernetes-basierte und nicht Kubernetes-basierte. Viele GDC-APIs sind Erweiterungen der Open-Source-Kubernetes-API. Sie verwenden benutzerdefinierte Kubernetes-Ressourcen und basieren auf dem KRM. Diese APIs sind wie die Kubernetes-API HTTP-basierte RESTful APIs, die standardmäßig JSON oder Protobuf akzeptieren und zurückgeben. Der API-Endpunkt ist der entsprechende Kubernetes-Server.

Andere, nicht Kubernetes-basierte GDC-APIs wie die vortrainierten Vertex AI-APIs haben eigene Endpunkte. Einige dieser APIs unterstützen nicht nur HTTP, sondern sind möglicherweise auch über gRPC zugänglich, das Open-Source-Framework für Remoteprozeduraufrufe. Weitere Informationen zu bestimmten APIs finden Sie in der entsprechenden Dokumentation im vertikalen Navigationsmenü.

Verwenden Sie die gdcloud CLI-Tools oder die GDC Console, um auf GDC-APIs zuzugreifen.

Kubernetes-API und KRM

Da viele GDC-APIs Erweiterungen der Kubernetes-API sind und auf dem KRM basieren, können Sie die GDC-APIs optimal nutzen, wenn Sie diese Konzepte verstehen.

Die Kubernetes-API ist vollständig deklarativ und alles in der Kubernetes-API ist eine Ressource, die dem KRM folgt. API-Clients, sowohl menschliche als auch maschinelle, führen Aktionen für diese Ressourcen aus, oft mit CRUD-Vorgängen (Create, Read, Update, Delete = Erstellen, Lesen, Aktualisieren und Löschen). Die Kubernetes-Datenbank speichert die Ressource und stellt den Status des Systems dar. Kubernetes beobachtet diese Ressourcen kontinuierlich und gleicht den tatsächlichen Status des Systems mit dem gewünschten Status ab. Wenn Sie beispielsweise eine Deployment-Ressource aktualisieren, um anzugeben, dass Sie fünf Replikate Ihres Containers anstelle von vier wünschen, erkennt Kubernetes die Änderung der gewünschten Anzahl von Replikaten und erstellt einen zusätzlichen Container.

Für die Kubernetes-Kern-API führt Kubernetes den Abgleich zwischen dem gewünschten und dem tatsächlichen Status selbst durch. Die Kubernetes-API-Erweiterungen sind benutzerdefinierte Ressourcen, die nicht Teil der Kubernetes-Kern-API sind. Die benutzerdefinierte Software beobachtet und interagiert kontinuierlich mit der Kubernetes-API und führt den Abgleich durch.

Weitere Informationen zur Kubernetes-API und zum Kubernetes-Ressourcenmodell finden Sie in der offiziellen Kubernetes-Dokumentation.

Globale und zonale APIs

Ressourcen in GDC mit Air Gap sind entweder zonale oder globale Ressourcen. Zonale Ressourcen arbeiten unabhängig voneinander innerhalb einer einzelnen Zone. Ein zonales Problem kann sich auf einige oder alle Ressourcen in dieser Zone auswirken. Globale Ressourcen arbeiten mit Redundanz über mehrere Zonen hinweg, um die Fehlertoleranz zu erhöhen.

GDC mit Air Gap bietet zwei Ebenen von APIs der Verwaltungsebene zum Erstellen und Verwalten beider GDC-Ressourcentypen: globale APIs und zonale APIs.

Sowohl globale als auch zonale APIs sind deklarative Kubernetes-APIs, die an verschiedenen Endpunkten bereitgestellt werden. GDC-Ressourcen werden in den API-Servern als benutzerdefinierte Kubernetes-Ressourcen dargestellt. Die globalen API-Server verwenden einen einzelnen etcd-Cluster, der über mehrere Zonen verteilt ist, um eine strikte Konsistenz mit Fehlertoleranz zu gewährleisten. Dies führt jedoch zu einer höheren Latenz und weniger Schreibabfragen pro Sekunde (QPS) im Vergleich zu den zonalen API-Servern. In jeder Organisation stellt ein zonales Management-API-Server die zonale API für Administratoren und Entwickler zum Verwalten von zonalen Ressourcen bereit. Ein globaler Management-API-Server stellt die globale API zum Verwalten von Ressourcen in mehreren Zonen bereit.

Zugriff auf GDC-APIs

Sowohl die gdcloud CLI-Tools als auch die GDC Console nutzen die GDC-APIs. Google empfiehlt, diese zu verwenden, um GDC zu erkunden oder einmalige Vorgänge auszuführen. Wenn Sie jedoch automatisierten oder programmatischen Zugriff auf GDC verwenden, empfiehlt Google, die GDC-APIs direkt zu verwenden.

HTTP- und gRPC-Unterstützung

Die meisten GDC-APIs bieten eine JSON-HTTP-Schnittstelle, die Sie direkt aufrufen können. Die Kubernetes-basierten APIs verwenden die Kubernetes-Clientbibliotheken. Einige nicht Kubernetes-basierte GDC-APIs haben eine gRPC-Schnittstelle, die eine verbesserte Leistung und Nutzerfreundlichkeit bietet. Google bietet auch Clientbibliotheken für GDC-APIs an, die nicht auf Kubernetes basieren. Weitere Informationen zu gRPC finden Sie unter https://grpc.io/.

TLS-Verschlüsselung

Alle GDC-APIs akzeptieren Anfragen mit TLS-Verschlüsselung (Transport Layer Security).

  • Wenn Sie eine der Kubernetes- oder GDC-Clientbibliotheken verwenden, übernimmt die Bibliothek die Verschlüsselung während der Übertragung für Sie.
  • Wenn Sie einen eigenen HTTP- oder gRPC-Client verwenden, müssen Sie sich bei GDC authentifizieren. Hierfür ist TLS erforderlich. Folgen Sie für gRPC der Anleitung im gRPC Authentifizierungsleitfaden unter https://grpc.io/docs/guides/auth/.

Auf die Kubernetes-API und Kubernetes-basierte APIs zugreifen

Die Kubernetes-CLI kubectl ist die primäre Methode, um direkt mit der Kubernetes-API und allen Kubernetes-basierten APIs zu arbeiten.

Zugriff mit kubectl

Verwenden Sie beim ersten Zugriff auf die Kubernetes-API das Kubernetes-Befehlszeilentool kubectl.

Für den Zugriff auf einen Cluster benötigen Sie die Standortinformationen des Clusters und die Anmeldedaten für den Zugriff. Im Abschnitt Anmelden erfahren Sie, wie Sie auf diese Anmeldedaten zugreifen.

Prüfen Sie Ihre aktuelle kubectl-Konfiguration und sehen Sie sich die Cluster an, auf die Sie Zugriff haben:

kubectl config view

API-Endpunktbeschreibungen generieren

Wenn Sie eine Liste der API-Endpunkte für alle Dienst-APIs in GDC mit Air Gap aufrufen möchten, können Sie API-Beschreibungen gemäß der OpenAPI-Spezifikation im JSON-Format generieren. Sie können das generierte JSON für die API-Endpunkte in Tools wie Swagger ansehen.

Führen Sie die folgenden Schritte aus, um die API-Endpunktbeschreibungen der Verwaltungs- und Datenebene im JSON-Format zu generieren:

  1. Erstellen Sie einen Proxyserver zwischen Ihrer Umgebung und dem Management-API-Server:

    kubectl proxy --kubeconfig MANAGEMENT_API_SERVER

    Ersetzen Sie MANAGEMENT_API_SERVER durch den Pfad zur kubeconfig-Datei des Management-API-Servers. Weitere Informationen finden Sie unter Ressourcen des zonalen Management-API-Servers.

  2. Laden Sie die Liste der API-Endpunktbeschreibungen im JSON-Format herunter:

    curl -s http://127.0.0.1:8001/openapi/v2 | jq 'if .paths then .paths = (.paths \
    | with_entries(select(.key | contains(".private") | not))) else . end' > k8s_swagger.json

  3. Öffnen Sie die generierte Datei k8s_swagger.json in einem Tool wie Swagger, um die API-Endpunktbeschreibungen anzusehen.

Direkter Zugriff auf die API mit einem HTTP-Client

Es gibt folgende Möglichkeiten, direkt mit einem HTTP-Client wie curl, wget oder einem Browser auf die REST API zuzugreifen:

  • Verlassen Sie sich auf kubectl, um die Authentifizierung zu verarbeiten, indem Sie es im Proxy-Modus verwenden.
  • Verarbeiten Sie die Authentifizierung selbst.
kubectl-Proxy ausführen

Der kubectl proxy Befehl führt kubectl in einem Modus aus, in dem es als Reverse Proxy fungiert. Dieser Befehl stellt eine Verbindung zum apiserver her und verwaltet die Authentifizierung.

Wenn Sie kubectl im Proxy-Modus ausführen, wird der gespeicherte API-Serverstandort verwendet und die Identität des API-Servers mit einem Zertifikat überprüft. Diese Methode schützt vor Man-in-the-Middle-Angriffen (MITM).

Das folgende Beispiel zeigt, wie Sie den Befehl kubectl proxy verwenden:

kubectl proxy --port=8080 &

Sobald der kubectl-Proxy ausgeführt wird, können Sie die API mit curl, wget oder einem Browser untersuchen, wie unten gezeigt:

$ curl http://localhost:8080/api/
{
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}
Ohne kubectl-Proxy ausführen

Wenn Sie kubectl nicht im Proxy-Modus ausführen möchten, können Sie ein Authentifizierungstoken direkt an den API-Server übergeben.

  1. Listen Sie alle möglichen Kubernetes-Cluster auf, auf die Sie Zugriff haben, da Ihre kubeconfig-Datei mehrere Kontexte haben kann:

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

  2. Exportieren Sie den Namen des Kubernetes-Clusters, mit dem Sie interagieren möchten, aus der vorherigen Ausgabe:

    export CLUSTER_NAME="CLUSTER_NAME"

  3. Legen Sie den API-Server fest, der auf den Namen des Kubernetes-Clusters verweist:

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

  4. Erstellen Sie ein Secret, um ein Token für das Standarddienstkonto zu speichern:

    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

  5. Warten Sie, bis der Token-Controller das Secret mit einem Token gefüllt hat:

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

  6. Legen Sie den Tokenwert fest:

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

  7. Um auf die API zuzugreifen, verwenden Sie das Token mit einem Tool wie curl, indem Sie den HTTP-Header Authorization: Bearer $TOKEN hinzufügen, wie im folgenden Beispiel gezeigt:

    $ curl -k $APISERVER/api --header "Authorization: Bearer $TOKEN"

    Die Ausgabe sieht etwa so aus:

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