Les interfaces de programmation d'application (API) Google Distributed Cloud (GDC) isolées sont des interfaces de programmation pour les services de la plate-forme GDC. Google crée les API du plan de contrôle sur Kubernetes, à l'aide du modèle de ressource Kubernetes (KRM). Le plan de contrôle effectue la gestion des ressources pour les services, comme la création, la suppression et les mises à jour.
Certains services disposent de ces API et de leurs propres API de plan de données, qui sont basées sur XML, JSON ou gRPC. Cette page aborde ces services dans leurs sections respectives.
À propos des API GDC
Il existe deux types d'API GDC : celles basées sur Kubernetes et celles qui ne le sont pas. De nombreuses API GDC sont des extensions de l'API Kubernetes Open Source. Ils utilisent des ressources personnalisées Kubernetes et s'appuient sur le KRM. Ces API, comme l'API Kubernetes, sont des API RESTful basées sur HTTP, qui acceptent et renvoient JSON par défaut, ou dans Protobuf. Le point de terminaison de l'API est le serveur Kubernetes concerné.
Les autres API GDC non basées sur Kubernetes, telles que les API d'IA pré-entraînée Vertex, ont leurs propres points de terminaison. En plus d'être compatibles avec HTTP, certaines de ces API peuvent également être accessibles par gRPC, le framework d'appel de procédure à distance Open Source. Pour en savoir plus sur des API spécifiques, consultez leur documentation dédiée dans le menu de navigation vertical.
Pour accéder aux API GDC, utilisez les outils gdcloud CLI ou la console GDC.
À propos de l'API Kubernetes et du KRM
Comme de nombreuses API GDC sont des extensions de l'API Kubernetes et s'appuient sur le KRM, la compréhension de ces concepts vous aide à exploiter pleinement les API GDC.
L'API Kubernetes est entièrement déclarative, et tout ce qui s'y trouve est une ressource qui suit le KRM. Les clients de l'API, qu'ils soient humains ou machines, agissent sur ces ressources, souvent avec des opérations de création, de lecture, de mise à jour et de suppression (CRUD). La base de données Kubernetes stocke la ressource et représente l'état du système. Kubernetes surveille en permanence ces ressources et rapproche l'état réel du système de l'état souhaité. Par exemple, si vous mettez à jour une ressource Deployment
pour indiquer que vous souhaitez cinq répliques de votre conteneur au lieu de quatre, Kubernetes détecte la modification du nombre de répliques souhaité et crée un conteneur supplémentaire.
Pour l'API Kubernetes de base, Kubernetes effectue lui-même la réconciliation entre les états souhaité et réel. Les extensions de l'API Kubernetes sont des ressources personnalisées qui ne font pas partie de l'API Kubernetes de base. Le logiciel personnalisé surveille et interagit en permanence avec l'API Kubernetes, et effectue la réconciliation.
Pour en savoir plus sur l'API Kubernetes et le modèle de ressources Kubernetes, consultez la documentation officielle de Kubernetes.
- Présentation de l'API Kubernetes, sur https://kubernetes.io/docs/reference/using-api/
- Concepts de l'API Kubernetes, à l'adresse https://kubernetes.io/docs/reference/using-api/api-concepts/
- Modèle de ressource Kubernetes (KRM), sur https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md
API globales et zonales
Les ressources dans GDC air-gapped sont des ressources zonales ou globales. Les ressources zonales fonctionnent de manière indépendante dans une seule zone. Une panne zonale peut affecter tout ou partie des ressources de cette zone. Les ressources mondiales fonctionnent avec une redondance dans plusieurs zones pour assurer la tolérance aux pannes.
GDC air-gapped propose deux niveaux d'API de plan de gestion pour créer et gérer les deux types de ressources GDC : les API globales et les API zonales.
Les API globales et zonales sont des API déclaratives Kubernetes diffusées à différents points de terminaison. Les ressources GDC sont représentées sous forme de ressources personnalisées Kubernetes dans les serveurs d'API. Les serveurs d'API mondiaux partagent un seul cluster etcd distribué sur plusieurs zones pour assurer une cohérence forte avec une tolérance aux pannes, au prix d'une latence plus élevée et d'un nombre de requêtes d'écriture par seconde (RPS) réduit par rapport aux serveurs d'API zonaux. Dans chaque organisation, un serveur d'API de gestion zonale fournit l'API zonale aux administrateurs et aux développeurs pour gérer les ressources zonales, et un serveur d'API de gestion globale fournit l'API globale pour gérer les ressources multizones.
Accès aux API GDC
Les outils gdcloud CLI et la console GDC exploitent les API GDC. Google vous recommande de les utiliser pour explorer GDC ou effectuer des opérations ponctuelles. Toutefois, si vous utilisez un accès automatique ou programmatique à GDC, Google vous recommande d'utiliser directement les API GDC.
Compatibilité avec HTTP et gRPC
La plupart des API GDC fournissent une interface HTTP JSON que vous pouvez appeler directement. Les API basées sur Kubernetes utilisent les bibliothèques clientes Kubernetes. Certaines API GDC non Kubernetes disposent d'une interface gRPC, qui améliore les performances et la facilité d'utilisation. Google fournit également des bibliothèques clientes pour les API GDC qui ne sont pas basées sur Kubernetes. Pour en savoir plus sur gRPC, consultez https://grpc.io/.
Chiffrement TLS
Toutes les API GDC acceptent les requêtes utilisant le chiffrement TLS (Transport Layer Security).
- Si vous utilisez l'une des bibliothèques clientes Kubernetes ou GDC, la bibliothèque gère le chiffrement en transit pour vous.
- Si vous utilisez votre propre client HTTP ou gRPC, vous devez vous authentifier auprès de GDC, ce qui nécessite TLS. Pour gRPC, suivez les instructions du guide d'authentification gRPC sur https://grpc.io/docs/guides/auth/.
Accéder à l'API Kubernetes et aux API basées sur Kubernetes
La CLI Kubernetes kubectl
est le principal moyen d'interagir directement avec l'API Kubernetes et toutes les API basées sur Kubernetes.
Accéder avec kubectl
Lorsque vous accédez à l'API Kubernetes pour la première fois, utilisez l'outil de ligne de commande Kubernetes, kubectl
.
Pour accéder à un cluster, vous avez besoin des informations sur son emplacement et des identifiants permettant d'y accéder. Consultez la section Se connecter pour savoir comment accéder à ces identifiants.
Examinez votre configuration kubectl
actuelle et consultez les clusters auxquels vous avez accès :
kubectl config view
Accès direct à l'API avec un client HTTP
Voici quelques façons d'accéder directement à l'API REST avec un client HTTP tel que curl
, wget
ou un navigateur :
- S'appuyer sur
kubectl
pour gérer l'authentification en l'utilisant en mode proxy. - Gérez vous-même l'authentification.
Exécuter kubectl proxy
La commande kubectl proxy
exécute kubectl
dans un mode où il sert de proxy inverse. Cette commande se connecte à apiserver
et gère l'authentification.
L'exécution de kubectl
en mode proxy utilise l'emplacement du serveur d'API stocké et vérifie l'identité du serveur d'API à l'aide d'un certificat. Cette méthode protège contre les attaques MITM ("man-in-the-middle").
L'exemple suivant montre comment utiliser la commande kubectl proxy
:
kubectl proxy --port=8080 &
Une fois le proxy kubectl
en cours d'exécution, vous pouvez explorer l'API avec curl
, wget
ou un navigateur, comme illustré ci-dessous :
$ curl http://localhost:8080/api/
{
"versions": [
"v1"
],
"serverAddressByClientCIDRs": [
{
"clientCIDR": "0.0.0.0/0",
"serverAddress": "10.0.1.149:443"
}
]
}
Exécuter sans le proxy kubectl
Si vous ne souhaitez pas exécuter kubectl
en mode proxy, vous pouvez transmettre un jeton d'authentification directement au serveur d'API.
Listez tous les clusters Kubernetes auxquels vous avez accès, car votre fichier kubeconfig peut comporter plusieurs contextes :
kubectl config view \ -o jsonpath='{"Cluster name\tServer\n"}{range.clusters[*]}{.name}{"\t"}{.cluster.server}{"\n"}{end}'
Exportez le nom du cluster Kubernetes avec lequel vous souhaitez interagir à partir de la sortie précédente :
export CLUSTER_NAME="CLUSTER_NAME"
Définissez le serveur d'API en faisant référence au nom du cluster Kubernetes :
APISERVER=$(kubectl config view -o jsonpath="{.clusters[?(@.name==\"$CLUSTER_NAME\")].cluster.server}")
Créez un secret pour stocker un jeton pour le compte de service par défaut :
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
Attendez que le contrôleur de jetons remplisse le secret avec un jeton :
while ! kubectl describe secret default-token | grep -E '^token' >/dev/null; do echo "waiting for token..." >&2 sleep 1 done
Définissez la valeur du jeton :
TOKEN=$(kubectl get secret $(kubectl get secrets | grep default | cut -f1 -d ' ') \ -o jsonpath='{.data.token}' | base64 --decode)
Pour accéder à l'API, utilisez le jeton avec un outil tel que
curl
en ajoutant l'en-tête HTTPAuthorization: Bearer $TOKEN
, comme indiqué dans l'exemple suivant :$ curl -k $APISERVER/api --header "Authorization: Bearer $TOKEN"
Le résultat ressemble à ce qui suit :
{ "kind": "APIVersions", "versions": [ "v1" ], "serverAddressByClientCIDRs": [ { "clientCIDR": "0.0.0.0/0", "serverAddress": "10.0.1.149:443" } ] }