Présentation des API Google Distributed Cloud sous air gap

Les interfaces de programmation d'application (API) air-gapped de Google Distributed Cloud (GDC) 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 ressources Kubernetes (KRM). Le plan de contrôle effectue la gestion des ressources pour des services tels que la création, la suppression et les mises à jour.

Les services spécifiques 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 couvre 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. Elles 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 au format Protobuf. Le point de terminaison de l'API est le serveur Kubernetes approprié.

D'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 de la prise en charge de 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

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 aidera à tirer pleinement parti des 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 d'API, humains et machines, agissent sur ces ressources, souvent avec des opérations CRUD (création, lecture, mise à jour et suppression). La base de données Kubernetes stocke la ressource et représente l'état du système. Kubernetes surveille en permanence ces ressources et réconcilie l'état réel du système avec 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.

API globales et zonales

Les ressources de GDC sous air gap 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 sur plusieurs zones pour 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 desservies 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 globaux partagent un seul cluster etcd réparti 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'une réduction des 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 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 de la CLI gdcloud et la console GDC exploitent les API GDC. Nous vous recommandons de les utiliser pour explorer GDC ou effectuer des opérations ponctuelles. Toutefois, si vous utilisez un accès automatisé ou programmatique à GDC, nous vous recommandons d'utiliser directement les API GDC.

Prise en charge de HTTP et gRPC

La plupart des API GDC fournissent une interface JSON HTTP que vous appelez 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 de meilleures performances et une plus grande 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, accédez à 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ès 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 pour y accéder. Consultez la section Se connecter pour savoir comment obtenir ces identifiants.

Examinez votre configuration kubectl actuelle et consultez 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 d'API dans des outils tels que Swagger.

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

  1. Créez un serveur proxy entre votre environnement et le serveur d'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 la section Ressources du serveur d'API de gestion zonale.

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

  3. 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érez vous-même l'authentification.
Exécuter kubectl proxy

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 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 kubectl proxy

Si vous ne souhaitez pas exécuter kubectl en mode proxy, vous pouvez transmettre directement un jeton d'authentification au serveur d'API.

  1. Répertoriez tous les clusters Kubernetes possibles 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}'

  2. Exportez le nom du cluster Kubernetes avec lequel vous souhaitez interagir à partir de la sortie précédente :

    export CLUSTER_NAME="CLUSTER_NAME"

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

  4. Créez un secret pour contenir 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

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

  6. Définissez la valeur du jeton :

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

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