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 piano di controllo su Kubernetes, utilizzando il modello di risorse Kubernetes (KRM). Il control plane esegue la gestione delle risorse per servizi come la creazione, l'eliminazione e gli aggiornamenti.

Servizi specifici hanno queste API e le proprie API del piano dati, 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 non basate su Kubernetes. Molte API GDC sono estensioni dell'API Kubernetes open source. Utilizzano risorse personalizzate di Kubernetes e si basano sul 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 di chiamata di procedure remote 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 della CLI gdcloud 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 al meglio le API GDC.

L'API Kubernetes è completamente dichiarativa e tutto ciò che è presente 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 lo stato desiderato. Ad esempio, se aggiorni una risorsa Deployment per indicare che vuoi cinque repliche del container anziché quattro, Kubernetes rileva la modifica del numero di repliche desiderato e crea un container aggiuntivo.

Per l'API Kubernetes di base, Kubernetes esegue la riconciliazione tra gli stati desiderato e 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 saperne di più sull'API Kubernetes e sul modello di risorse Kubernetes, consulta la documentazione ufficiale di Kubernetes.

API globali e di zona

Le risorse in GDC con air gap sono risorse 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 della zona. Le risorse globali operano con ridondanza in più zone per la tolleranza agli errori.

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.

Le API globali e di zona sono API dichiarative di Kubernetes servite su 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 la tolleranza agli errori, a costo di una latenza maggiore e di una riduzione delle 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 di gestione globale fornisce l'API globale per gestire le risorse multizona.

Accesso alle API 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 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 saperne di più su gRPC, visita 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.
  • Se utilizzi il tuo client HTTP o gRPC, devi autenticarti con GDC, che richiede TLS. Per gRPC, segui le istruzioni 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 Kubernetes kubectl è il modo principale per interagire direttamente con l'API Kubernetes e con qualsiasi API basata su Kubernetes.

Accedere 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 località del cluster e delle credenziali di accesso. Consulta la sezione Accedere 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

Generare descrizioni degli endpoint API

Per visualizzare un elenco degli 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 questi passaggi per generare le descrizioni degli endpoint API del piano di gestione e del piano dati in formato JSON:

  1. Crea un server proxy tra il tuo ambiente e il server 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 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.

Accedere direttamente 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.
  • Gestisci l'autenticazione autonomamente.
Eseguire 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 località 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 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"
    }
  ]
}
Eseguire 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 cluster Kubernetes possibili 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}'

  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 dei token popoli il secret con un token:

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

  6. Imposta il valore del token:

    TOKEN=$(kubectl get secret $(kubectl get secrets | grep default | cut -f1 -d ' ')  \
    -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"
    }
  ]
}