L'API Kubernetes

Le cœur du plan de contrôle de Kubernetes est le serveur API. Le serveur API expose une API HTTP qui permet aux utilisateurs finaux, aux différentes parties de votre cluster et aux composants externes de communiquer entre eux.

L'API Kubernetes vous permet d'interroger et de manipuler l'état des objets API dans Kubernetes (par exemple : Pods, Namespaces, ConfigMaps et Events).

La plupart des opérations peuvent être effectuées via l'interface de ligne de commande kubectl ou d'autres outils en ligne de commande, tels que kubeadm, qui utilisent à leur tour l'API. Cependant, vous pouvez également accéder à l'API directement en utilisant des appels REST. Kubernetes fournit un ensemble de bibliothèques clientes pour ceux qui souhaitent écrire des applications utilisant l'API Kubernetes.

Chaque cluster Kubernetes publie la spécification des API qu'il sert. Il existe deux mécanismes que Kubernetes utilise pour publier ces spécifications d'API ; les deux sont utiles pour permettre une interopérabilité automatique. Par exemple, l'outil kubectl récupère et met en cache l'API spécification pour activer l'auto-complétion en ligne de commande et d'autres fonctionnalités. Les deux mécanismes pris en charge sont les suivants :

• L'API Discovery fournit des informations sur les API Kubernetes : noms des API, ressources, versions et opérations prises en charge. Il s'agit d'un terme spécifique à Kubernetes car il s'agit d'une API distincte de l'API OpenAPI de Kubernetes. Il est destiné à être un bref résumé des ressources disponibles et il ne détaille pas le schéma spécifique des ressources. Pour des références sur les schémas de ressources, veuillez vous référer au document OpenAPI.

• Le document OpenAPI de Kubernetes fournit des schémas (complets) OpenAPI v2.0 et 3.0 pour tous les points d'extrémité de l'API Kubernetes. L'OpenAPI v3 est la méthode préférée pour accéder à l'OpenAPI car il offre une vue plus complète et précise de l'API. Il inclut tous les chemins d'API disponibles, ainsi que toutes les ressources consommées et produites pour chaque opération sur chaque point d'extrémité. Il inclut également les composants d'extensibilité pris en charge par un cluster. Les données sont une spécification complète et sont significativement plus grandes que celles de l'API Discovery.

API Discovery

Kubernetes publie une liste de toutes les versions de groupe et de toutes les ressources prises en charge via l'API Discovery. Cela inclut les éléments suivants pour chaque ressource :

• Nom
• Portée du cluster ou du namespace
• URL de l'endpoint et verbes pris en charge
• Noms alternatifs
• Groupe, version, type

L'API est disponible sous forme agrégée et non agrégée. La découverte agrégée propose deux endpoints tandis que la découverte non agrégée propose un endpoint distinct pour chaque version de groupe.

Découverte agrégée

Kubernetes propose une prise en charge stable de la découverte agrégée, publiant toutes les ressources prises en charge par un cluster via deux endpoints (/api et /apis). En demandant cela, l'endpoint réduit considérablement le nombre de requêtes envoyées pour récupérer les données de découverte du cluster. Vous pouvez accéder aux données en demandant les endpoints respectifs avec un en-tête Accept indiquant la ressource de découverte agrégée : Accept: application/json;v=v2;g=apidiscovery.k8s.io;as=APIGroupDiscoveryList.

Sans indiquer le type de ressource à l'aide de l'en-tête Accept, la réponse par défaut pour les endpoints /api et /apis est un document de découverte non agrégé.

Le document de découverte pour les ressources intégrées peut être trouvé dans le référentiel GitHub de Kubernetes. Ce document GitHub peut être utilisé comme référence pour l'ensemble de base des ressources disponibles si un cluster Kubernetes n'est pas disponible pour la requête.

L'endpoint prend également en charge l'ETag et l'encodage protobuf.

Découverte non agrégée

Sans agrégation de découverte, la découverte est publiée par niveaux, avec les endpoints racine publiant les informations de découverte pour les documents en aval.

Une liste de toutes les versions de groupe prises en charge par un cluster est publiée à les endpoints /api et /apis. Exemple :

{
  "kind": "APIGroupList",
  "apiVersion": "v1",
  "groups": [
    {
      "name": "apiregistration.k8s.io",
      "versions": [
        {
          "groupVersion": "apiregistration.k8s.io/v1",
          "version": "v1"
        }
      ],
      "preferredVersion": {
        "groupVersion": "apiregistration.k8s.io/v1",
        "version": "v1"
      }
    },
    {
      "name": "apps",
      "versions": [
        {
          "groupVersion": "apps/v1",
          "version": "v1"
        }
      ],
      "preferredVersion": {
        "groupVersion": "apps/v1",
        "version": "v1"
      }
    },
    ...
}

Des requêtes supplémentaires sont nécessaires pour obtenir le document de découverte pour chaque version de groupe à /apis/<group>/<version> (par exemple : /apis/rbac.authorization.k8s.io/v1alpha1), qui annonce la liste des ressources servies sous une version de groupe particulière. Ces endpoints sont utilisés par kubectl pour récupérer la liste des ressources prises en charge par un cluster.

Pour plus de détails sur les spécifications OpenAPI, consultez la documentation OpenAPI.

Kubernetes prend en charge à la fois OpenAPI v2.0 et OpenAPI v3.0. OpenAPI v3 est la méthode préférée pour accéder à l'OpenAPI car elle offre une représentation plus complète (sans perte) des ressources Kubernetes. En raison des limitations de la version 2 d'OpenAPI, certains champs sont supprimés de l'OpenAPI publié, y compris mais sans s'y limiter default, nullable, oneOf.

OpenAPI V2

Le serveur API Kubernetes sert une spécification OpenAPI v2 agrégée via l'endpoint /openapi/v2. Vous pouvez demander le format de réponse en utilisant les en-têtes de requête comme suit :

OpenAPI V3

Kubernetes prend en charge la publication d'une description de ses API en tant qu'OpenAPI v3.

Un endpoint de découverte /openapi/v3 est fourni pour voir une liste de tous les groupes/versions disponibles. Cet endpoint ne renvoie que du JSON. Ces groupes/versions sont fournis dans le format suivant :

{
    "paths": {
        ...,
        "api/v1": {
            "serverRelativeURL": "/openapi/v3/api/v1?hash=CC0E9BFD992D8C59AEC98A1E2336F899E8318D3CF4C68944C3DEC640AF5AB52D864AC50DAA8D145B3494F75FA3CFF939FCBDDA431DAD3CA79738B297795818CF"
        },
        "apis/admissionregistration.k8s.io/v1": {
            "serverRelativeURL": "/openapi/v3/apis/admissionregistration.k8s.io/v1?hash=E19CC93A116982CE5422FC42B590A8AFAD92CDE9AE4D59B5CAAD568F083AD07946E6CB5817531680BCE6E215C16973CD39003B0425F3477CFD854E89A9DB6597"
        },
        ....
    }
}

Les URLs relatives pointent vers des descriptions OpenAPI immuables, afin d'améliorer la mise en cache côté client. Les en-têtes de mise en cache HTTP appropriés sont également définis par le serveur API à cette fin (Expires à 1 an dans le futur, et Cache-Control à immutable). Lorsqu'une URL obsolète est utilisée, le serveur API renvoie une redirection vers la nouvelle URL.

Le serveur API Kubernetes publie une spécification OpenAPI v3 par version de groupe Kubernetes à l'endpoint /openapi/v3/apis/<group>/<version>?hash=<hash>.

Reportez-vous au tableau ci-dessous pour les en-têtes de requête acceptés.

Une implémentation en Golang pour récupérer l'OpenAPI V3 est fournie dans le package k8s.io/client-go/openapi3.

Kubernetes 1.34 publie OpenAPI v2.0 et v3.0 ; il n'y a pas de plans pour prendre en charge la version 3.1 dans un avenir proche.

Sérialisation Protobuf

Kubernetes implémente un format de sérialisation alternatif basé sur Protobuf qui est principalement destiné à la communication intra-cluster. Pour plus d'informations sur ce format, consultez la proposition de conception Kubernetes Protobuf serialization et les fichiers de langage de définition d'interface (IDL) pour chaque schéma situés dans les packages Go qui définissent les objets de l'API.

Persistance

Kubernetes stocke l'état sérialisé des objets en les écrivant dans etcd.

Groupes d'API et versioning

Pour faciliter l'élimination de champs ou la restructuration des représentations de ressources, Kubernetes prend en charge plusieurs versions d'API, chacune à un chemin d'API différent, tel que /api/v1 ou /apis/rbac.authorization.k8s.io/v1alpha1.

Le versioning est effectué au niveau de l'API plutôt qu'au niveau de la ressource ou du champ pour garantir que l'API présente une vue claire et cohérente des ressources et du comportement du système, et pour permettre de contrôler l'accès aux API en fin de vie et/ou expérimentales.

Pour faciliter l'évolution et l'extension de son API, Kubernetes implémente des groupes d'API qui peuvent être activés ou désactivés.

Les ressources de l'API sont distinguées par leur groupe d'API, leur type de ressource, leur namepaces (pour les ressources avec namespace) et leur nom. Le serveur API gère la conversion entre les versions d'API de manière transparente : toutes les différentes versions sont en réalité des représentations des mêmes données persistées. Le serveur API peut servir les mêmes données sous plusieurs versions d'API.

Par exemple, supposons qu'il existe deux versions d'API, v1 et v1beta1, pour la même ressource. Si vous avez initialement créé un objet en utilisant la version v1beta1 de son API, vous pouvez ensuite lire, mettre à jour ou supprimer cet objet en utilisant soit la version v1beta1 soit la version v1 de l'API, jusqu'à ce que la version v1beta1 soit dépréciée et supprimée. À ce moment-là, vous pouvez continuer à accéder et à modifier l'objet en utilisant l'API v1.

Changements d'API

Tout système qui réussit doit évoluer et changer à mesure que de nouveaux cas d'utilisation émergent ou que les cas d'utilisation existants changent. Par conséquent, Kubernetes a conçu l'API Kubernetes pour changer et évoluer en permanence. Le projet Kubernetes vise à ne pas rompre la compatibilité avec les clients existants et à maintenir cette compatibilité pendant une certaine période afin que d'autres projets aient l'opportunité de s'adapter.

En général, de nouvelles ressources d'API et de nouveaux champs de ressources peuvent être ajoutés souvent et fréquemment. L'élimination de ressources ou de champs nécessite de suivre la politique de dépréciation de l'API.

Kubernetes s'engage fermement à maintenir la compatibilité avec les API Kubernetes officielles une fois qu'elles atteignent la disponibilité générale (GA), généralement à la version d'API v1. De plus, Kubernetes maintient la compatibilité avec les données persistées via les versions d'API beta des API Kubernetes officielles, et garantit que les données peuvent être converties et accessibles via les versions d'API GA lorsque la fonctionnalité devient stable.

Si vous adoptez une version d'API beta, vous devrez passer à une version d'API beta ou stable ultérieure une fois que l'API aura été promue. Le meilleur moment pour le faire est pendant la période de dépréciation de l'API beta, car les objets sont accessibles simultanément via les deux versions d'API. Une fois que l'API beta a terminé sa The Kubernetes project aims to not break compatibility with existing clients, and to maintain that La compatibilité est un élément essentiel dans l'évolution de l'API Kubernetes. De nouvelles ressources et de nouveaux champs peuvent être ajoutés fréquemment, tandis que la suppression de ressources ou de champs nécessite de suivre la politique de dépréciation de l'API.

Consultez la référence des versions d'API pour plus de détails sur les définitions de niveau de version d'API.

Extension d'API

L'API Kubernetes peut être étendue de deux manières :

1. Les ressources personnalisées vous permettent de définir de manière déclarative comment le serveur API doit fournir votre API de ressource choisie.
2. Vous pouvez également étendre l'API Kubernetes en implémentant une couche d'agrégation.

A suivre

• Apprenez comment étendre l'API Kubernetes en ajoutant votre propre CustomResourceDefinition.
• Contrôler l'accès à l'API Kubernetes décrit comment le cluster gère l'authentification et l'autorisation pour l'accès à l'API.
• Apprenez-en davantage sur les points de terminaison de l'API, les types de ressources et les exemples en lisant Référence de l'API.
• Apprenez ce qui constitue un changement compatible et comment modifier l'API à partir de Changements d'API.