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

Die Application Programming Interfaces (APIs) von Google Distributed Cloud (GDC) mit Air Gap sind programmatische Schnittstellen zu den GDC-Plattformdiensten. Google erstellt die APIs der Steuerungsebene auf der Grundlage von Kubernetes und verwendet dazu das Kubernetes-Ressourcenmodell (KRM). Die Steuerungsebene übernimmt die Ressourcenverwaltung für Dienste, z. B. Erstellung, Löschung und Aktualisierungen.

Bestimmte Dienste haben diese APIs und ihre eigenen Datenebenen-APIs, die XML-, JSON- oder gRPC-basiert sind. Diese Dienste werden auf dieser Seite in den entsprechenden Abschnitten behandelt.

Informationen zu 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 relevante Kubernetes-Server.

Andere, nicht Kubernetes-basierte GDC APIs, z. B. die vortrainierten Vertex AI APIs, haben eigene Endpunkte. Zusätzlich zur Unterstützung von HTTP können einige dieser APIs auch über gRPC, das Open-Source-Framework für Remote-Prozeduraufrufe, aufgerufen werden. Weitere Informationen zu bestimmten APIs finden Sie in der entsprechenden Dokumentation im vertikalen Navigationsmenü.

Verwenden Sie für den Zugriff auf GDC APIs 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, hilft Ihnen ein Verständnis dieser Konzepte, die GDC APIs in vollem Umfang zu nutzen.

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, agieren mit diesen Ressourcen, oft mit CRUD-Vorgängen (Create, Read, Update, Delete). Die Kubernetes-Datenbank speichert die Ressource und stellt den Status des Systems dar. Kubernetes überwacht diese Ressourcen kontinuierlich und gleicht den tatsächlichen Zustand des Systems mit dem gewünschten Zustand ab. Wenn Sie beispielsweise eine Deployment-Ressource aktualisieren, um anzugeben, dass Sie fünf Replikate Ihres Containers anstelle von vier möchten, erkennt Kubernetes die Änderung der gewünschten Anzahl von Replikaten und erstellt einen zusätzlichen Container.

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

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

• Kubernetes API-Übersicht unter 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 mit Air Gap sind entweder zonale oder globale Ressourcen. Zonale Ressourcen arbeiten unabhängig voneinander innerhalb einer einzelnen Zone. Ein zonaler Ausfall kann sich auf einige oder alle Ressourcen in dieser Zone auswirken. Globale Ressourcen werden redundant in mehreren Zonen bereitgestellt, um Fehlertoleranz zu gewährleisten.

GDC mit Air Gap bietet zwei Ebenen von APIs für die Verwaltungsebene, um beide GDC-Ressourcentypen zu erstellen und zu verwalten: globale APIs und zonale APIs.

Sowohl globale als auch zonale APIs sind deklarative Kubernetes-APIs, die an verschiedenen Endpunkten bereitgestellt werden. GDC-Ressourcen werden auf den API-Servern als benutzerdefinierte Kubernetes-Ressourcen dargestellt. Die globalen API-Server nutzen einen einzelnen etcd-Cluster, der über Zonen verteilt ist, um eine strikte Konsistenz mit Fehlertoleranz zu bieten. Dies geht jedoch im Vergleich zu den zonalen API-Servern mit einer höheren Latenz und einer geringeren Anzahl von Schreibabfragen pro Sekunde (QPS) einher. In jeder Organisation stellt ein zonaler Verwaltungs-API-Server die zonale API für Administratoren und Entwickler bereit, um zonale Ressourcen zu verwalten. Ein globaler API-Server stellt die globale API bereit, um Ressourcen in mehreren Zonen zu verwalten.

Zugriff auf GDC-APIs

Sowohl die gdcloud CLI-Tools als auch die GDC-Konsole 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 GDC-APIs, die nicht auf Kubernetes basieren, haben eine gRPC-Schnittstelle, die eine bessere Leistung und Nutzerfreundlichkeit bietet. Google stellt auch Clientbibliotheken für GDC APIs bereit, 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 Ihren eigenen HTTP- oder gRPC-Client verwenden, müssen Sie sich bei GDC authentifizieren, wofür TLS erforderlich ist. Folgen Sie für gRPC 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. Das Erstellen eines eigenen API-Clients ist eine mühsame Softwareentwicklungsaufgabe, die bei falscher Ausführung zu unvorhergesehenem Verhalten in Ihren Systemen führen kann, das schwer zu diagnostizieren ist.

Auf die Kubernetes API und Kubernetes-basierte APIs zugreifen

Die Kubernetes-Befehlszeile kubectl ist die primäre Möglichkeit, 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. Informationen zum Zugriff auf diese Anmeldedaten finden Sie im Abschnitt Anmelden.

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

kubectl config view

Beschreibungen für API-Endpunkt generieren

Wenn Sie eine Liste der API-Endpunkte aufrufen möchten, die für alle Dienst-APIs in GDC mit Air Gap verfügbar sind, 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 für die 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 Verwaltungs-API-Servers. Weitere Informationen finden Sie unter Zonale Management API-Serverressourcen.

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 k8s_swagger.json-Datei in einem Tool wie Swagger, um die Beschreibungen der API-Endpunkt aufzurufen.

Direkter Zugriff auf die API mit einem HTTP-Client

Im Folgenden finden Sie Möglichkeiten, mit einem HTTP-Client wie curl, wget oder einem Browser direkt auf die REST API zuzugreifen:

• Verwenden Sie kubectl im Proxymodus, um die Authentifizierung zu verarbeiten.
• Sie übernehmen die Authentifizierung selbst.

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 Sie kubectl im Proxymodus ausführen, 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 (MITM).

Im folgenden Beispiel wird die Verwendung des Befehls kubectl proxy gezeigt:

kubectl proxy --port=8080 &

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

$ 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 den API-Server übergeben.

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

   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 sich auf den Kubernetes-Clusternamen bezieht:

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

4. Erstellen Sie ein Secret für ein Token für das Standarddienstkonto:

   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 füllt:

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

6. Legen Sie den Tokenwert fest:

   TOKEN=$(kubectl get secret default-token -n NAMESPACE \
       -o jsonpath='{.data.token}' | base64 --decode)
   

7. Wenn Sie auf die API zugreifen möchten, verwenden Sie das Token mit einem Tool wie curl. Fügen Sie dazu den HTTP-Header Authorization: Bearer $TOKEN hinzu, 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"
       }
     ]
   }