Diese Seite wurde von der Cloud Translation API übersetzt.

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

Die Air-Gap-APIs (Application Programming Interfaces) von Google Distributed Cloud (GDC) 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. Auf dieser Seite werden diese Dienste 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, 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.

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/.

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

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}'
```
Exportieren Sie den Namen des Kubernetes-Clusters, mit dem Sie interagieren möchten, aus der vorherigen Ausgabe:
```
export CLUSTER_NAME="CLUSTER_NAME"
```

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}")

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

Warten Sie, bis der Token-Controller das Secret mit einem Token füllt:

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

Legen Sie den Tokenwert fest:

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

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