Questa pagina è stata tradotta dall'API Cloud Translation.

Panoramica delle API Google Distributed Cloud con air gap

Le interfacce di programmazione delle applicazioni (API) air-gapped di Google Distributed Cloud (GDC) 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 servizi come la creazione, l'eliminazione e gli aggiornamenti.

Servizi specifici dispongono di queste API e delle proprie API data plane, che sono basate su XML, JSON o gRPC. Questa pagina tratta 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 su KRM. Queste API, come l'API Kubernetes, sono API RESTful basate su HTTP, che accettano e restituiscono JSON come formato predefinito o in Protobuf. L'endpoint API è il server Kubernetes pertinente.

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

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

Informazioni sull'API Kubernetes e sul KRM

Poiché molte 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 contiene è 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 tuo container anziché quattro, Kubernetes rileva la modifica del numero desiderato di repliche e crea un container aggiuntivo.

Per l'API Kubernetes di base, Kubernetes esegue la riconciliazione tra gli stati desiderati e reali. 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 saperne 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/
Kubernetes API Concepts, 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 zonali

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

GDC air-gapped offre due livelli di API del control plane per creare e gestire entrambi i tipi di risorse GDC: API globali e API di zona.

Le API globali e di zona sono API dichiarative di Kubernetes pubblicate su endpoint diversi e le risorse GDC sono rappresentate come risorse personalizzate di Kubernetes nei server API. I server API globali condividono un unico cluster etcd distribuito tra le zone per fornire unaelevata coerenzaa con tolleranza agli errori, a costo di una latenza maggiore 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 zonale fornisce l'API zonale per consentire ad amministratori e sviluppatori di gestire le risorse zonali, mentre un server API di gestione globale fornisce l'API globale per gestire le risorse multizona.

Accesso alle API di GDC

Sia gli strumenti della CLI 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 ti 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 Kubernetes. Alcune API GDC non Kubernetes hanno un'interfaccia gRPC, che offre prestazioni e usabilità migliori. Google fornisce anche librerie client per le API GDC che non si basano su Kubernetes. Per saperne di più su gRPC, visita la 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 Kubernetes o GDC, la libreria gestisce la crittografia in transito per te.
Se utilizzi un client HTTP o gRPC personalizzato, 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/.

Accedere all'API Kubernetes e alle API basate su Kubernetes

La CLI kubectl Kubernetes è il modo principale per interagire direttamente con l'API Kubernetes e qualsiasi API basata su Kubernetes.

Accesso con kubectl

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

Per accedere a un cluster, devi disporre delle informazioni 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

Accesso diretto all'API con un client HTTP

Di seguito sono riportati alcuni 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.
Gestisci l'autenticazione autonomamente.

Esegui kubectl proxy

Il comando kubectl proxy esegue kubectl in una modalità in cui funge da proxy inverso. Questo comando si connette a apiserver e gestisce l'autenticazione.

L'esecuzione di kubectl in modalità proxy utilizza la posizione del server API memorizzata 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 eseguito il proxy kubectl, 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 trasmettere un token di autenticazione direttamente al server API.

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

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

Esporta il nome del cluster Kubernetes con cui vuoi interagire dall'output precedente:
```
export CLUSTER_NAME="CLUSTER_NAME"
```

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

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

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

Attendi che il controller dei token inserisca un token nel secret:

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

Imposta il valore del token:

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

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