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

Die APIs (Application Programming Interfaces) für Google Distributed Cloud (GDC) mit Air Gap sind programmatische Schnittstellen zu den GDC-Plattformdiensten. Google entwickelt die APIs der Steuerungsebene auf Kubernetes aufbauend und verwendet dabei das Kubernetes-Ressourcenmodell (Kubernetes Resource Model, KRM). Die Steuerungsebene führt die Ressourcenverwaltung für Dienste aus, z. B. zum Erstellen, Löschen und Aktualisieren.

Bestimmte Dienste haben diese APIs und eigene Data-Plane-APIs, die auf XML, JSON oder gRPC basieren können. Sie werden in den entsprechenden Abschnitten auf dieser Seite beschrieben.

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, wie die Kubernetes API, sind HTTP-basierte RESTful APIs, die standardmäßig JSON oder Protobuf akzeptieren und zurückgeben. Der API-Endpunkt ist der relevante Kubernetes-Server.

Andere, nicht auf Kubernetes basierende GDC-APIs wie die vortrainierten Vertex AI-APIs haben eigene Endpunkte. Neben HTTP werden einige dieser APIs möglicherweise auch von gRPC unterstützt, dem Open-Source-Framework für Remoteprozeduraufrufe. Weitere Informationen zu bestimmten APIs finden Sie in der entsprechenden Dokumentation im vertikalen Navigationsmenü.

Für den Zugriff auf GDC-APIs verwenden Sie die gdcloud-CLI-Tools oder die GDC-Konsole.

Kubernetes API und KRM

Da viele der GDC-APIs Erweiterungen der Kubernetes-API sind und auf dem KRM basieren, ist es hilfreich, diese Konzepte zu verstehen, um die GDC-APIs optimal nutzen zu können.

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, greifen auf diese Ressourcen zu, oft mit CRUD-Vorgängen (Create, Read, Update, Delete). In der Kubernetes-Datenbank wird die Ressource gespeichert und der Status des Systems dargestellt. Kubernetes überwacht 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.

Bei der Kubernetes-Kern-API führt Kubernetes den Abgleich zwischen gewünschtem und tatsächlichem Status selbst durch. Die Kubernetes API-Erweiterungen sind benutzerdefinierte Ressourcen, die nicht Teil der Kubernetes-Kern-API sind. Die benutzerdefinierte Software überwacht und interagiert kontinuierlich mit der Kubernetes API und führt die Abstimmung durch.

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

• Kubernetes API – Übersicht: https://kubernetes.io/docs/reference/using-api/
• Kubernetes API-Konzepte unter https://kubernetes.io/docs/reference/using-api/api-concepts/
• Das Kubernetes-Ressourcenmodell (KRM) unter https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md

Globale und zonale APIs

Ressourcen in GDC Air-Gapped sind entweder zonale oder globale Ressourcen. Zonale Ressourcen arbeiten unabhängig voneinander innerhalb einer einzigen Zone. Ein zonales Problem kann sich auf einige oder alle Ressourcen in dieser Zone auswirken. Globale Ressourcen werden redundant in mehreren Zonen bereitgestellt, um Fehlertoleranz zu gewährleisten.

Hinweis: Das Multi-Zonen-Verwaltungssystem ist eine Vorschaufunktion.

GDC Air-Gapped bietet zwei Ebenen von Managementplane-APIs 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 nutzen einen einzelnen etcd-Cluster, der über Zonen verteilt ist, um eine starke Konsistenz mit Fehlertoleranz zu bieten. Dies geht jedoch auf Kosten einer höheren Latenz und einer geringeren Anzahl von Schreibanfragen pro Sekunde (QPS) im Vergleich zu den zonenbasierten API-Servern. In jeder Organisation stellt ein zonaler 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-Konsole nutzen die GDC-APIs. Google empfiehlt, diese für einmalige Vorgänge oder zum Erkunden von GDC zu verwenden. Wenn Sie jedoch automatisierten oder programmatischen Zugriff auf GDC verwenden, empfiehlt Google, die GDC-APIs direkt zu nutzen.

Unterstützung von HTTP und gRPC

Die meisten GDC-APIs bieten eine JSON-HTTP-Schnittstelle, die Sie direkt aufrufen können. Die Kubernetes-basierten APIs verwenden die Kubernetes-Clientbibliotheken. Einige GDC-APIs, die nicht auf Kubernetes basieren, haben eine gRPC-Schnittstelle, die eine bessere 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, wird die Verschlüsselung während der Übertragung automatisch von der Bibliothek übernommen.
• Wenn Sie einen eigenen HTTP- oder gRPC-Client verwenden, müssen Sie sich bei GDC authentifizieren. Hierfür ist TLS erforderlich. Für gRPC folgen Sie der Anleitung im gRPC-Authentifizierungsleitfaden unter https://grpc.io/docs/guides/auth/.

Hinweis :GDC empfiehlt, vorhandene Clients, insbesondere von Google bereitgestellte, für die Interaktion mit GDC-APIs zu verwenden. Die Entwicklung eines eigenen API-Clients ist eine anspruchsvolle Softwareentwicklungsaufgabe, die bei unsachgemäßer Ausführung zu unvorhergesehenen Verhaltensweisen in Ihren Systemen führen kann, die schwer zu diagnostizieren sind.

Auf die Kubernetes API und Kubernetes-basierte APIs zugreifen

Die kubectl-Kubernetes-Befehlszeile 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.

Um auf einen Cluster zuzugreifen, 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 können.

Sehen Sie sich Ihre aktuelle kubectl-Konfiguration an und prüfen Sie, auf welche Cluster Sie Zugriff haben:

kubectl config view

Direkter Zugriff auf die API mit einem HTTP-Client

Sie haben 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 im Proxymodus zu verarbeiten.
• Sie kümmern sich selbst um die Authentifizierung.

kubectl-Proxy ausführen

Mit dem Befehl kubectl proxy wird kubectl in einem Modus ausgeführt, in dem es als Reverse-Proxy fungiert. Mit diesem Befehl wird eine Verbindung zu apiserver hergestellt und die Authentifizierung verwaltet.

Wenn kubectl im Proxymodus ausgeführt wird, wird der gespeicherte API-Serverstandort verwendet und die Identität des API-Servers wird mithilfe eines Zertifikats überprüft. Diese Methode schützt vor Man-in-the-Middle-Angriffen.

Im folgenden Beispiel wird gezeigt, wie der Befehl kubectl proxy verwendet wird:

kubectl proxy --port=8080 &

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

$ 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 Proxymodus ausführen möchten, können Sie ein Authentifizierungstoken direkt an apiserver übergeben. Ersetzen Sie [YOUR_CLUSTER] in den folgenden Befehlen durch den Namen des Clusters, mit dem Sie interagieren möchten:

# 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)

Nachdem Sie das Token in der Umgebungsvariable $TOKEN exportiert haben, können Sie es mit einem Tool wie curl verwenden, indem Sie den HTTP-Header Authorization: Bearer $TOKEN hinzufügen, wie im folgenden Beispiel gezeigt:

$ 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"
    }
  ]
}