Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Présentation des API Google Distributed Cloud sous air gap

Les interfaces de programmation d'application (API) de Google Distributed Cloud (GDC) avec isolation physique 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 gère les ressources des services, par exemple en les créant, en les supprimant et en les mettant à 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 traite de 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 par défaut des données au format JSON ou 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ées 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 la documentation dédiée dans le menu de navigation vertical.

Pour accéder aux API GDC, utilisez les outils de la CLI gdcloud ou la console GDC.

À propos de l'API Kubernetes et du KRM

Étant donné que de nombreuses API GDC sont des extensions de l'API Kubernetes et s'appuient sur le KRM, une bonne 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 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 instances répliquées de votre conteneur au lieu de quatre, Kubernetes détecte la modification du nombre d'instances répliquées souhaité et crée un conteneur supplémentaire.

Pour l'API Kubernetes principale, Kubernetes effectue lui-même le rapprochement entre l'état souhaité et l'état réel. Les extensions de l'API Kubernetes sont des ressources personnalisées qui ne font pas partie de l'API Kubernetes principale. Le logiciel personnalisé surveille et interagit en permanence avec l'API Kubernetes, et effectue le rapprochement.

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, sur https://kubernetes.io/docs/reference/using-api/api-concepts/
Le 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 de GDC air-gapped sont soit des ressources zonales, soit des ressources globales. Les ressources zonales fonctionnent indépendamment dans une seule zone, et une panne zonale peut affecter tout ou partie des ressources de cette zone. Les ressources globales fonctionnent avec une redondance dans plusieurs zones pour assurer la tolérance aux pannes.

GDC sous air gap 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 sur différents points de terminaison, et les ressources GDC sont représentées en tant que ressources personnalisées Kubernetes dans les serveurs d'API. Les serveurs d'API mondiaux partagent un seul cluster etcd réparti entre les zones pour assurer une cohérence forte avec tolérance aux pannes, au détriment d'une latence plus élevée et d'un nombre réduit de requêtes d'écriture par seconde (RPS) par rapport aux serveurs d'API zonaux. Dans chaque organisation, un serveur d'API de gestion zonale fournit l'API zonale permettant aux administrateurs et aux développeurs de gérer les ressources zonales, et un serveur d'API global fournit l'API globale permettant de gérer les ressources multizones.

Accès aux API GDC

Les outils de la CLI gdcloud 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 automatisé ou programmatique à GDC, Google vous recommande d'utiliser directement les API GDC.

Compatibilité 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 offre des performances et une facilité d'utilisation améliorées. 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 de travailler 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 de localisation du cluster 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 affichez les clusters auxquels vous avez accès :

kubectl config view

Générer des descriptions de points de terminaison d'API

Pour afficher la liste des points de terminaison de l'API disponibles pour toutes les API de service dans GDC sous air gap, vous pouvez générer des descriptions d'API en suivant la spécification OpenAPI au format JSON. Vous pouvez afficher le code JSON généré pour les points de terminaison de l'API dans des outils tels que Swagger.

Pour générer les descriptions des points de terminaison de l'API du plan de gestion et du plan de données au format JSON, procédez comme suit :

Créez un serveur proxy entre votre environnement et le serveur de l'API de gestion :
```
kubectl proxy --kubeconfig MANAGEMENT_API_SERVER
```
Remplacez MANAGEMENT_API_SERVER par le chemin d'accès au fichier kubeconfig du serveur d'API de gestion. Pour en savoir plus, consultez Ressources du serveur d'API de gestion zonale.

Téléchargez la liste des descriptions des points de terminaison d'API au format JSON :

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

Ouvrez le fichier k8s_swagger.json généré dans un outil tel que Swagger pour afficher les descriptions des points de terminaison de l'API.

Accès direct à l'API avec un client HTTP

Voici comment accéder directement à l'API REST avec un client HTTP tel que curl, wget ou un navigateur :

Utilisez kubectl pour gérer l'authentification en l'utilisant en mode proxy.
Gérer l'authentification vous-même.

Exécuter le proxy kubectl

La commande kubectl proxy exécute kubectl dans un mode où il agit comme un 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 de type "man-in-the-middle" (MITM).

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 indiqué 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 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.

Répertoriez tous les clusters Kubernetes auxquels vous avez accès, car votre fichier kubeconfig peut avoir 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 du résultat précédent :
```
export CLUSTER_NAME="CLUSTER_NAME"
```

Définissez le serveur d'API 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 contenant 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 jeton renseigne le secret avec un jeton :

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

Définissez la valeur du jeton :

TOKEN=$(kubectl get secret default-token -n NAMESPACE \
    -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 HTTP Authorization: Bearer $TOKEN, comme illustré 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"
    }
  ]
}