Panoramica delle API Google Distributed Cloud con air gap

Le interfacce di programmazione di un'applicazione (API) di Google Distributed Cloud (GDC) con air gap sono interfacce programmatiche per i servizi della piattaforma GDC. Google crea le API del control plane su Kubernetes, utilizzando il Kubernetes Resource Model (KRM). Il control plane esegue la gestione delle risorse per i servizi, ad esempio la creazione, l'eliminazione e gli aggiornamenti.

Servizi specifici dispongono di queste API e delle proprie API del piano dati, che sono basate su XML, JSON o gRPC. Questa pagina illustra questi servizi nelle rispettive sezioni.

Informazioni sulle API GDC

Esistono due tipi di API GDC: quelle basate su Kubernetes e quelle che non lo sono. Molte API GDC sono estensioni dell'API Kubernetes open source. Utilizzano risorse personalizzate Kubernetes e si basano sul KRM. Queste API, come l'API Kubernetes, sono API RESTful basate su HTTP che accettano e restituiscono JSON per impostazione predefinita o in Protobuf. L'endpoint API è il server Kubernetes pertinente.

Altre API GDC non basate su Kubernetes, come le API di AI preaddestrate di Vertex, hanno i propri endpoint. Oltre a supportare HTTP, alcune di queste API potrebbero essere accessibili anche tramite gRPC, il framework di chiamata di procedura remota open source. Per ulteriori informazioni su API specifiche, consulta la documentazione dedicata nel menu di navigazione verticale.

Per accedere alle API GDC, utilizza gli strumenti CLI gdcloud o la console GDC.

Informazioni sull'API Kubernetes e sul KRM

Poiché molte delle API GDC sono estensioni dell'API Kubernetes e si basano sul KRM, la comprensione di questi concetti ti aiuta a sfruttare appieno le API GDC.

L'API Kubernetes è completamente dichiarativa e tutto ciò che si trova nell'API Kubernetes è una risorsa che segue il KRM. I client API, sia umani che automatici, agiscono su queste risorse, spesso con operazioni di creazione, lettura, aggiornamento ed eliminazione (CRUD). Il database Kubernetes archivia la risorsa e rappresenta lo stato del sistema. Kubernetes monitora continuamente queste risorse e riconcilia lo stato reale del sistema con quello desiderato. Ad esempio, se aggiorni una risorsa Deployment per indicare che vuoi cinque repliche del container anziché quattro, Kubernetes rileva la modifica nel numero di repliche desiderato e crea un container aggiuntivo.

Per l'API Kubernetes di base, Kubernetes esegue la riconciliazione tra lo stato desiderato e quello reale. Le estensioni dell'API Kubernetes sono risorse personalizzate che non fanno parte dell'API Kubernetes di base. Il software personalizzato monitora e interagisce continuamente con l'API Kubernetes ed esegue la riconciliazione.

Per scoprire di più sull'API Kubernetes e sul modello di risorse Kubernetes, consulta la documentazione ufficiale di Kubernetes.

• Panoramica dell'API Kubernetes, all'indirizzo https://kubernetes.io/docs/reference/using-api/
• Concetti relativi all'API Kubernetes, all'indirizzo https://kubernetes.io/docs/reference/using-api/api-concepts/
• Il modello di risorse Kubernetes (KRM), all'indirizzo https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md

API globali e di zona

Le risorse in GDC con air gap sono risorse di zona o risorse globali. Le risorse di zona operano in modo indipendente all'interno di una singola zona e un'interruzione a livello di zona può influire su alcune o tutte le risorse di quella zona. Le risorse globali operano con ridondanza in più zone per la tolleranza di errore.

GDC con air gap offre due livelli di API del piano di gestione per creare e gestire entrambi i tipi di risorse GDC: API globali e API di zona.

Sia le API globali che quelle di zona sono API dichiarative di Kubernetes gestite in endpoint diversi e le risorse GDC sono rappresentate come risorse personalizzate di Kubernetes nei server API. I server API globali condividono un singolo cluster etcd distribuito tra le zone per fornire un'elevata coerenza con tolleranza di errore, al costo di una latenza più elevata e di un numero ridotto di query di scrittura al secondo (QPS) rispetto ai server API di zona. In ogni organizzazione, un server API di gestione di zona fornisce l'API di zona per consentire ad amministratori e sviluppatori di gestire le risorse di zona, mentre un server API globale fornisce l'API globale per gestire le risorse multizona.

Accesso alle API GDC

Sia gli strumenti dell'interfaccia a riga di comando gdcloud sia la console GDC sfruttano le API GDC. Google consiglia di utilizzarli per esplorare GDC o per eseguire operazioni una tantum. Tuttavia, se utilizzi l'accesso automatico o programmatico a GDC, Google consiglia di utilizzare direttamente le API GDC.

Supporto di HTTP e gRPC

La maggior parte delle API GDC fornisce un'interfaccia HTTP JSON che puoi chiamare direttamente. Le API basate su Kubernetes utilizzano le librerie client di Kubernetes. Alcune API GDC non Kubernetes hanno un'interfaccia gRPC, che offre prestazioni e usabilità migliorate. Google fornisce anche librerie client per le API GDC non basate su Kubernetes. Per scoprire di più su gRPC, vai alla pagina https://grpc.io/.

Crittografia TLS

Tutte le API GDC accettano richieste che utilizzano la crittografia TLS (Transport Layer Security).

• Se utilizzi una delle librerie client di Kubernetes o GDC, la libreria gestisce la crittografia in transito per te.
• Se utilizzi il tuo client HTTP o gRPC, devi eseguire l'autenticazione con GDC, che richiede TLS. Per gRPC, segui le istruzioni riportate nella guida all'autenticazione gRPC all'indirizzo https://grpc.io/docs/guides/auth/.

Nota: GDC consiglia di utilizzare i client esistenti, in particolare quelli forniti da Google, per interagire con le API GDC. La creazione di un client API personalizzato è un'attività di ingegneria del software complessa che, se eseguita in modo errato, potrebbe causare comportamenti imprevisti nei sistemi difficili da diagnosticare.

Accedi all'API Kubernetes e alle API basate su Kubernetes

L'interfaccia a riga di comando di Kubernetes kubectl è il modo principale per lavorare direttamente con l'API Kubernetes e con qualsiasi API basata su Kubernetes.

Accesso con kubectl

Quando accedi all'API Kubernetes per la prima volta, utilizza lo strumento a riga di comando di Kubernetes, kubectl.

Per accedere a un cluster, devi disporre dei dati sulla posizione del cluster e delle credenziali per accedervi. Consulta la sezione Accedi per scoprire come ottenere l'accesso a queste credenziali.

Esamina la configurazione kubectl attuale e visualizza i cluster a cui hai accesso:

kubectl config view

Genera descrizioni degli endpoint API

Per visualizzare un elenco di endpoint API disponibili per tutte le API di servizio in GDC con air gap, puoi generare descrizioni delle API seguendo la specifica OpenAPI in formato JSON. Puoi visualizzare il JSON generato per gli endpoint API in strumenti come Swagger.

Completa i seguenti passaggi per generare le descrizioni degli endpoint API del piano di gestione e dei dati in formato JSON:

1. Crea un server proxy tra il tuo ambiente e il server dell'API di gestione:

   kubectl proxy --kubeconfig MANAGEMENT_API_SERVER
   

   Sostituisci MANAGEMENT_API_SERVER con il percorso del file kubeconfig del server API di gestione. Per saperne di più, consulta Risorse del server API di gestione a livello di zona.

2. Scarica l'elenco delle descrizioni degli endpoint API in formato 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. Apri il file k8s_swagger.json generato in uno strumento come Swagger per visualizzare le descrizioni degli endpoint API.

Accesso diretto all'API con un client HTTP

Di seguito sono riportati i modi per accedere direttamente all'API REST con un client HTTP come curl, wget o un browser:

• Affidati a kubectl per gestire l'autenticazione utilizzandolo in modalità proxy.
• Gestire l'autenticazione in autonomia.

Esegui kubectl proxy

Il comando kubectl proxy esegue kubectl in una modalità in cui agisce come reverse proxy. Questo comando si connette a apiserver e gestisce l'autenticazione.

L'esecuzione di kubectl in modalità proxy utilizza la posizione del server API archiviata e verifica l'identità del server API utilizzando un certificato. Questo metodo protegge dagli attacchi man in the middle (MITM).

L'esempio seguente mostra come utilizzare il comando kubectl proxy:

kubectl proxy --port=8080 &

Una volta che il proxy kubectl è in esecuzione, puoi esplorare l'API con curl, wget o un browser, come mostrato di seguito:

$ curl http://localhost:8080/api/
{
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}

Esegui senza kubectl proxy

Se non vuoi eseguire kubectl in modalità proxy, puoi passare un token di autenticazione direttamente al server API.

1. Elenca tutti i possibili cluster Kubernetes a cui hai accesso, poiché il tuo file kubeconfig potrebbe avere più contesti:

   kubectl config view \
       -o jsonpath='{"Cluster name\tServer\n"}{range.clusters[*]}{.name}{"\t"}{.cluster.server}{"\n"}{end}'
   

2. Esporta il nome del cluster Kubernetes con cui vuoi interagire dall'output precedente:

   export CLUSTER_NAME="CLUSTER_NAME"
   

3. Imposta il server API facendo riferimento al nome del cluster Kubernetes:

   APISERVER=$(kubectl config view -o jsonpath="{.clusters[?(@.name==\"$CLUSTER_NAME\")].cluster.server}")
   

4. Crea un secret per contenere un token per il account di servizio predefinito:

   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. Attendi che il controller del token compili il secret con un token:

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

6. Imposta il valore del token:

   TOKEN=$(kubectl get secret default-token -n NAMESPACE \
       -o jsonpath='{.data.token}' | base64 --decode)
   

7. Per accedere all'API, utilizza il token con uno strumento come curl aggiungendo l'intestazione HTTP Authorization: Bearer $TOKEN come mostrato nell'esempio seguente:

   curl -k $APISERVER/api --header "Authorization: Bearer $TOKEN"
   

   L'output è simile al seguente:

   {
     "kind": "APIVersions",
     "versions": [
       "v1"
     ],
     "serverAddressByClientCIDRs": [
       {
         "clientCIDR": "0.0.0.0/0",
         "serverAddress": "10.0.1.149:443"
       }
     ]
   }