Le API di Kubernetes

Le convenzioni generali seguite dalle API sono descritte in API conventions doc.

Gli endpoints delle API, la lista delle risorse esposte ed i relativi esempi sono descritti in API Reference.

L'accesso alle API da remoto è discusso in Controllare l'accesso alle API.

Le API di Kubernetes servono anche come riferimento per lo schema dichiarativo della configurazione del sistema stesso. Il comando kubectl può essere usato per creare, aggiornare, cancellare ed ottenere le istanze delle risorse esposte attraverso le API.

Kubernetes assicura la persistenza del suo stato (al momento in etcd) usando la rappresentazione delle risorse implementata dalle API.

Kubernetes stesso è diviso in differenti componenti, i quali interagiscono tra loro attraverso le stesse API.

Evoluzione delle API

In base alla nostra esperienza, ogni sistema di successo ha bisogno di evolvere ovvero deve estendersi aggiungendo funzionalità o modificare le esistenti per adattarle a nuovi casi d'uso. Le API di Kubernetes sono quindi destinate a cambiare e ad estendersi. In generale, ci si deve aspettare che nuove risorse vengano aggiunte di frequente cosi come nuovi campi possano altresì essere aggiunti a risorse esistenti. L'eliminazione di risorse o di campi devono seguire la politica di deprecazione delle API.

In cosa consiste una modifica compatibile e come modificare le API è descritto dal API change document.

Definizioni OpenAPI e Swagger

La documentazione completa e dettagliata delle API è fornita attraverso la specifica OpenAPI.

Dalla versione 1.10 di Kubernetes, l'API server di Kubernetes espone le specifiche OpenAPI attraverso il seguente endpoint /openapi/v2. Attraverso i seguenti headers HTTP è possibile richiedere un formato specifico:

Prima della versione 1.14, gli endpoints che includono il formato del nome all'interno del segmento (/swagger.json, /swagger-2.0.0.json, /swagger-2.0.0.pb-v1, /swagger-2.0.0.pb-v1.gz) espongo le specifiche OpenAPI in formati differenti. Questi endpoints sono deprecati, e saranno rimossi dalla versione 1.14 di Kubernetes.

Esempi per ottenere le specifiche OpenAPI:

Kubernetes implementa per le sue API anche una serializzazione alternativa basata sul formato Protobuf che è stato pensato principalmente per la comunicazione intra-cluster, documentato nella seguente design proposal, e i files IDL per ciascun schema si trovano nei Go packages che definisco i tipi delle API.

Prima della versione 1.14, l'apiserver di Kubernetes espone anche un'endpoint, /swaggerapi, che può essere usato per ottenere le documentazione per le API di Kubernetes secondo le specifiche Swagger v1.2 . Questo endpoint è deprecato, ed è stato rimosso nella versione 1.14 di Kubernetes.

Versionamento delle API

Per facilitare l'eliminazione di campi specifici o la modifica della rappresentazione di una data risorsa, Kubernetes supporta molteplici versioni della stessa API disponibili attraverso differenti indirizzi, come ad esempio /api/v1 oppure /apis/extensions/v1beta1.

Abbiamo deciso di versionare a livello di API piuttosto che a livello di risorsa o di campo per assicurare che una data API rappresenti una chiara, consistente vista delle risorse di sistema e dei sui comportamenti, e per abilitare un controllo degli accessi sia per le API in via di decommissionamento che per quelle sperimentali.

Si noti che il versionamento delle API ed il versionamento del Software sono indirettamente collegati. La API and release versioning proposal descrive la relazione tra le versioni delle API ed le versioni del Software.

Differenti versioni delle API implicano differenti livelli di stabilità e supporto. I criteri per ciascuno livello sono descritti in dettaglio nella API Changes documentation. Queste modifiche sono qui ricapitolate:

• Livello alpha:
  • Il nome di versione contiene alpha (e.g. v1alpha1).
  • Potrebbe contenere dei bug. Abilitare questa funzionalità potrebbe esporre al rischio di bugs. Disabilitata di default.
  • Il supporto di questa funzionalità potrebbe essere rimosso in ogni momento senza previa notifica.
  • Questa API potrebbe cambiare in modo incompatibile in rilasci futuri del Software e senza previa notifica.
  • Se ne raccomandata l'utilizzo solo in clusters di test creati per un breve periodo di vita, a causa di potenziali bugs e delle mancanza di un supporto di lungo periodo.
• Livello beta:
  • Il nome di versione contiene beta (e.g. v2beta3).
  • Il codice è propriamente testato. Abilitare la funzionalità è considerato sicuro. Abilitata di default.
  • Il supporto per la funzionalità nel suo complesso non sarà rimosso, tuttavia potrebbe subire delle modifiche.
  • Lo schema e/o la semantica delle risorse potrebbe cambiare in modo incompatibile in successivi rilasci beta o stabili. Nel caso questo dovesse verificarsi, verrano fornite istruzioni per la migrazione alla versione successiva. Questo potrebbe richiedere la cancellazione, modifica, e la ri-creazione degli oggetti supportati da questa API. Questo processo di modifica potrebbe richiedere delle valutazioni. La modifica potrebbe richiedere un periodo di non disponibilità dell'applicazione che utilizza questa funzionalità.
  • Raccomandata solo per applicazioni non critiche per la vostra impresa a causa dei potenziali cambiamenti incompatibili in rilasci successivi. Se avete più clusters che possono essere aggiornati separatamente, potreste essere in grado di gestire meglio questa limitazione.
  • Per favore utilizzate le nostre versioni beta e forniteci riscontri relativamente ad esse! Una volta promosse a stabili, potrebbe non essere semplice apportare cambiamenti successivi.
• Livello stabile:
  • Il nome di versione è vX dove X è un intero.
  • Le funzionalità relative alle versioni stabili continueranno ad essere presenti per parecchie versioni successive.

API groups

Per facilitare l'estendibilità delle API di Kubernetes, sono stati implementati gli API groups.
L'API group è specificato nel percorso REST ed anche nel campo apiVersion di un oggetto serializzato.

Al momento ci sono diversi API groups in uso:

1. Il gruppo core, spesso referenziato come il legacy group, è disponibile al percorso REST /api/v1 ed utilizza apiVersion: v1.

2. I gruppi basati su un nome specifico sono disponibili attraverso il percorso REST /apis/$GROUP_NAME/$VERSION, ed usano apiVersion: $GROUP_NAME/$VERSION (e.g. apiVersion: batch/v1). La lista completa degli API groups supportati e' descritta nel documento Kubernetes API reference.

Vi sono due modi per supportati per estendere le API attraverso le custom resources:

1. CustomResourceDefinition è pensato per utenti con esigenze CRUD basilari.
2. Utenti che necessitano di un nuovo completo set di API che utilizzi appieno la semantica di Kubernetes possono implementare il loro apiserver ed utilizzare l'aggregator per fornire ai propri utilizzatori la stessa esperienza a cui sono abituati con le API incluse nativamente in Kubernetes.

Abilitare o disabilitare gli API groups

Alcune risorse ed API groups sono abilitati di default. Questi posso essere abilitati o disabilitati attraverso il settaggio/flag --runtime-config applicato sull'apiserver. --runtime-config accetta valori separati da virgola. Per esempio: per disabilitare batch/v1, usa la seguente configurazione --runtime-config=batch/v1=false, per abilitare batch/v2alpha1, utilizzate --runtime-config=batch/v2alpha1.
Il flag accetta set di coppie chiave/valore separati da virgola che descrivono la configurazione a runtime dell'apiserver.

Nota: Abilitare o disabilitare risorse o gruppi richiede il riavvio dell'apiserver e del controller-manager affinché le modifiche specificate attraverso il flag --runtime-config abbiano effetto.

Abilitare specifiche risorse nel gruppo extensions/v1beta1

DaemonSets, Deployments, StatefulSet, NetworkPolicies, PodSecurityPolicies e ReplicaSets presenti nel gruppo di API extensions/v1beta1 sono disabilitate di default. Per esempio: per abilitare deployments and daemonsets, utilizza la seguente configurazione --runtime-config=extensions/v1beta1/deployments=true,extensions/v1beta1/daemonsets=true.

Nota: Abilitare/disabilitare una singola risorsa è supportato solo per il gruppo di API extensions/v1beta1 per ragioni storiche.