kubernetes-api added in doc/overview

Author: crixo

content/it/docs/concepts/overview/kubernetes-api.md

@@ -0,0 +1,126 @@
+---
+title: Le API di Kubernetes 
+content_template: templates/concept
+weight: 30
+card: 
+  name: concepts
+  weight: 20
+---
+
+{{% capture overview %}}
+
+Le convenzioni generali seguite dalle API sono descritte in [API conventions doc](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md).
+
+Gli *endpoints* delle API, la lista delle risorse esposte ed i relativi esempi sono descritti in [API Reference](/docs/reference).
+
+L'accesso alle API da remoto è discusso in [Controllare l'accesso alle API](/docs/reference/access-authn-authz/controlling-access/).
+
+Le API di Kubernetes servono anche come riferimento per lo schema dichiarativo della configurazione del sistema stesso. Il comando [kubectl](/docs/reference/kubectl/overview/) 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](https://coreos.com/docs/distributed-configuration/getting-started-with-etcd/)) usando la rappresentazione delle risorse implementata dalle API.
+
+Kubernetes stesso è diviso in differenti componenti, i quali interagiscono tra loro attraverso le stesse API.
+
+{{% /capture %}}
+
+
+{{% capture body %}}
+
+## 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](/docs/reference/using-api/deprecation-policy/).
+
+In cosa consiste una modifica compatibile e come modificare le API è descritto dal [API change document](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md).
+
+## Definizioni OpenAPI e Swagger
+
+La documentazione completa e dettagliata delle API è fornita attraverso la specifica [OpenAPI](https://www.openapis.org/).
+
+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:
+
+Header | Possibili Valori
+------ | ---------------
+Accept | `application/json`, `application/[email protected]+protobuf` (il content-type di default è `application/json` per `*/*` ovvero questo header può anche essere omesso)
+Accept-Encoding | `gzip` (questo header è facoltativo)
+
+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**:
+
+Prima della 1.10 | Dalla versione 1.10 di Kubernetes
+---------------- | -----------------------------
+GET /swagger.json | GET /openapi/v2 **Accept**: application/json
+GET /swagger-2.0.0.pb-v1 | GET /openapi/v2 **Accept**: application/[email protected]+protobuf
+GET /swagger-2.0.0.pb-v1.gz | GET /openapi/v2 **Accept**: application/[email protected]+protobuf **Accept-Encoding**: gzip
+
+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](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/protobuf.md), 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](http://swagger.io/) .
+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](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md) 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](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions). 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*](https://git.k8s.io/community/contributors/design-proposals/api-machinery/api-group.md).  
+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`.
+
+1. 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](/docs/reference/).
+
+Vi sono due modi per supportati per estendere le API attraverso le [*custom resources*](/docs/concepts/api-extension/custom-resources/):
+
+1. [CustomResourceDefinition](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/)
+   è pensato per utenti con esigenze CRUD basilari.
+1. 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*](/docs/tasks/access-kubernetes-api/configure-aggregation-layer/)
+   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*.
+
+{{< note >}}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.{{< /note >}}
+
+## 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`.
+
+{{< note >}}Abilitare/disabilitare una singola risorsa è supportato solo per il gruppo di API `extensions/v1beta1` per ragioni storiche.{{< /note >}}
+
+{{% /capture %}}