Configurazione dell'API

È possibile utilizzare l'API IBM Cloud® Kubernetes Service per creare e gestire i cluster della propria community Kubernetes o Red Hat OpenShift. Per utilizzare la CLI, vedi Configurazione della CLI.

Informazioni sull'API

L'API di IBM Cloud Kubernetes Service automatizza il provisioning e la gestione delle risorse dell'infrastruttura IBM Cloud per i tuoi cluster in modo che le tue applicazioni dispongano delle risorse di calcolo, rete e archiviazione necessarie per servire gli utenti.

L'API supporta i diversi fornitori di infrastrutture disponibili per la creazione di cluster. Per ulteriori informazioni, vedi Panoramica del fornitore dell'infrastruttura.

Puoi utilizzare l'API della versione due (v2) per gestire i cluster sia classici che VPC. L'API v2 è progettata per evitare l'interruzione della funzionalità esistente laddove possibile. Tuttavia, assicurati di esaminare le seguenti differenze tra l'API v1 e v2.

Prefisso endpoint API
API v1: https://containers.cloud.ibm.com/global/v1
API v2: https://containers.cloud.ibm.com/global/v2
v3 API: https://containers.cloud.ibm.com/global/v3
Documenti di riferimento API
v1 e v2 API
v3 API.
Stile dell'architettura API
v1 API: Representational State Transfer (REST), incentrata sulle risorse con cui si interagisce tramite metodi dell' HTTP, quali GET, POST, PUT, PATCH e DELETE.
v2 API: Chiamate di procedura remota ( RPC ) incentrate su azioni eseguibili esclusivamente tramite i metodi GET, POST e HTTP.
Piattaforme del contenitore supportate
v1 API: Utilizza l'API " IBM Cloud Kubernetes Service " per gestire le risorse dell'infrastruttura di IBM Cloud, come i nodi di lavoro, per **sia i cluster "community" Kubernetes che quelli Red Hat OpenShift **.
v2 API: Utilizza l'API " IBM Cloud Kubernetes Service v2 " per gestire le risorse dell'infrastruttura di IBM Cloud, come i nodi di lavoro, per **sia i cluster VPC di community Kubernetes che quelli di Red Hat OpenShift **.
API Kubernetes
v1 API: per utilizzare l'API Kubernetes per gestire le risorse di Kubernetes all'interno del cluster, come i pod o gli spazi dei nomi, consultare la sezione " Utilizzo del cluster tramite l'API Kubernetes".
v2 API: come descritto all'indirizzo v1; vedere la sezione " Utilizzo del cluster tramite l'API Kubernetes".
API supportate per tipo di infrastruttura
API v1: classic
API v2: vpc e classic
  • Il provider vpc è progettato per supportare più provider secondari VPC. Il subprovider VPC supportato è vpc-gen2, che corrisponde a un cluster VPC per risorse di calcolo di Generazione 2.
  • Le richieste specifiche per il provider hanno un parametro di percorso nell'URL, come ad esempio v2/vpc/createCluster. Alcune API sono disponibili solo per un determinato provider, ad esempio GET vlan per l'infrastruttura classica o GET vpcs per VPC.
  • Le richieste indipendenti dal provider possono includere un parametro del corpo specifico per il provider, specificato dall'utente, solitamente in formato JSON, come ad esempio {"provider": "vpc"}, se si desidera ottenere risposte solo per il provider specificato.
GET risposte
v1 API: Il metodo GET per un insieme di risorse (ad esempio GET v1/clusters) restituisce gli stessi dettagli per ciascuna risorsa dell'elenco, proprio come il metodo GET per una singola risorsa (ad esempio GET v1/clusters/{idOrName}).
v2 API: Per garantire risposte più rapide, il metodo v2 GET relativo a un insieme di risorse (ad esempio GET v2/clusters) restituisce solo un sottoinsieme delle informazioni fornite in dettaglio dal metodo GET relativo a una singola risorsa (ad esempio GET v2/clusters/{idOrName}). Alcune risposte all'elenco includono una proprietà dei provider per identificare se l'elemento restituito si applica all'infrastruttura classica o VPC. Ad esempio, l'elenco GET zones restituisce alcuni risultati come mon01 che sono disponibili solo nel provider dell'infrastruttura classica, mentre altri risultati come us-south-01 sono disponibili solo nel provider dell'infrastruttura VPC.
Risposte del cluster, nodo di lavoro e pool di nodi di lavoro
v1 API: Le risposte includono solo informazioni specifiche relative al provider di infrastruttura classica, quali le VLAN presenti in un cluster di GET e e le risposte dei worker.
v2 API: Le informazioni restituite variano a seconda del fornitore dell'infrastruttura. Per tali risposte specifiche per il provider, puoi specificare il provider nella tua richiesta. Ad esempio, i cluster VPC non restituiscono informazioni VLAN poiché non hanno VLAN. Invece, restituiscono informazioni sulla sottorete e sulla rete CIDR.

Automazione delle distribuzioni dei cluster con l'API

Puoi utilizzare l'API IBM Cloud Kubernetes Service per automatizzare la creazione, la distribuzione e la gestione dei tuoi cluster Kubernetes.

L'API IBM Cloud Kubernetes Service richiede informazioni di intestazione che devi fornire nella tua richiesta API e che possono variare in base all'API che vuoi utilizzare. Per individuare quali informazioni di intestazione sono necessarie per la tua API, consulta la documentazione dell'API " IBM Cloud Kubernetes Service ".

Per l'autenticazione con IBM Cloud Kubernetes Service, devi fornire un token IBM Cloud IAM (Identity and Access Management) che viene generato con le tue credenziali IBM Cloud e che include l'ID dell'account IBM Cloud in cui è stato creato il cluster. A seconda del modo con cui ti autentichi con IBM Cloud, puoi scegliere tra le seguenti opzioni per automatizzare la creazione del tuo token IBM Cloud IAM.

ID non federato
  • Generare una chiave API IBM Cloud: In alternativa all'utilizzo del nome utente e della password di IBM Cloud, è possibile utilizzare le chiavi API di IBM Cloud. IBM Cloud Le chiavi API dipendono dall'account IBM Cloud per cui sono state generate. Non è possibile associare la propria chiave API di IBM Cloud a un ID account diverso all'interno dello stesso token IAM di IBM Cloud. Per accedere ai cluster che sono stati creati con un account diverso da quello su cui si basa la tua chiave API IBM Cloud, devi accedere all'account per generare una nuova chiave API.
  • Nome utente e password IBM Cloud: puoi seguire la procedura indicata in questo argomento per automatizzare completamente la creazione del tuo token di accesso IBM Cloud IAM.
ID federato
  • Genera una chiave API IBM Cloud: IBM Cloud le chiavi API dipendono dall'account IBM Cloud per cui sono generate. Non è possibile associare la propria chiave API di IBM Cloud a un ID account diverso all'interno dello stesso token IAM di IBM Cloud. Per accedere ai cluster che sono stati creati con un account diverso da quello su cui si basa la tua chiave API IBM Cloud, devi accedere all'account per generare una nuova chiave API.
  • Utilizza un codice di accesso monouso: se effettui l'autenticazione su IBM Cloud utilizzando un codice di accesso monouso, non è possibile automatizzare completamente la creazione del token IAM IBM Cloud, poiché il recupero del codice di accesso monouso richiede un'interazione manuale con il browser web. Per automatizzare completamente la creazione del tuo token IBM Cloud IAM, devi creare invece una chiave API IBM Cloud.
  • Chiave API: Per generare la chiave IBM Cloud Chiave API, procedere come segue.
    1. Dalla barra dei menu, fai clic su Gestisci > Accesso (IAM).
    2. Fai clic sulla pagina Utenti e quindi seleziona te stesso.
    3. Nel riquadro Chiavi API, fai clic su Crea una chiave API IBM Cloud.
    4. Immetti un Nome e una Descrizione per la tua chiave API e fai clic su Crea.
    5. Fai clic su Mostra per vedere la chiave API che è stata generata per te.
    6. Copia la chiave API in modo che tu possa utilizzarla per richiamare il tuo nuovo token di accesso IBM Cloud IAM.

  1. Crea il tuo token di accesso IBM Cloud IAM. Le informazioni sul corpo incluse nella tue richiesta variano in base al metodo di autenticazione IBM Cloud che utilizzi.

    POST https://iam.cloud.ibm.com/identity/token
    Intestazione
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic Yng6Yng= dove Yng6Yng= corrisponde all’autorizzazione codificata con il metodo URL per il nome utente bx e la password bx.
    Corpo per il nome utente e la password IBM Cloud.
    • grant_type: password
    • username: il tuo nome utente IBM Cloud.
    • password: la tua password IBM Cloud.
    Corpo per le chiavi API IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: la tua chiave API IBM Cloud
    Corpo per il passcode monouso IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • passcode: il tuo passcode monouso IBM Cloud. Esegui ibmcloud login --sso e segui le istruzioni nel tuo output della CLI per richiamare il tuo passcode monouso utilizzando il tuo browser web.

    Il seguente esempio mostra l'output per la richiesta precedente.

    {
"access_token": "<iam_access_token>",
"refresh_token": "<iam_refresh_token>",
"token_type": "Bearer",
"expires_in": 3600,
"expiration": 1493747503
"scope": "ibm openid"
}

    È possibile trovare il token IAM " IBM Cloud " nel campo " access_token " dell'output dell'API. Prendi nota del token IBM Cloud IAM per richiamare ulteriori informazioni di intestazione nei passi successivi.

  2. Richiama l'ID dell'account IBM Cloud che desideri utilizzare. Sostituisci TOKEN con il token IAM IBM Cloud che hai recuperato dal campo access_token dell'output dell'API nel passaggio precedente. Nel tuo output API, puoi trovare l'ID del tuo account IBM Cloud nel campo resources.metadata.guid.

    GET https://accounts.cloud.ibm.com/coe/v2/accounts
    Intestazione
    • Content-Type: application/json
    • Authorization: bearer TOKEN
    • Accept: application/json

    Il seguente esempio mostra l'emissione della richiesta precedente.

    {
"next_url": null,
"total_results": 5,
"resources": [
    {
        "metadata": {
            "guid": "<account_ID>",
            "url": "/coe/v2/accounts/<account_ID>",
            "created_at": "2016-09-29T02:49:41.842Z",
            "updated_at": "2018-08-16T18:56:00.442Z",
            "anonymousId": "1111a1aa1a1111a1aa11aa11111a1111"
        },
        "entity": {
            "name": "<account_name>",

  3. Genera un nuovo token IBM Cloud IAM che include le tue credenziali IBM Cloud e l'ID account che desideri utilizzare.

    Se utilizzi una chiave API IBM Cloud, devi usare l'ID account IBM Cloud per il quale è stata creata la chiave API. Per accedere ai cluster di altri account, accedi a questo account e crea una chiave API di IBM Cloud associata a questo account.

    POST https://iam.cloud.ibm.com/identity/token
    Intestazione
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic Yng6Yng= dove Yng6Yng= corrisponde all’autorizzazione codificata con il metodo URL per il nome utente bx e la password bx.
    Corpo per il nome utente e la password IBM Cloud.
    • grant_type: password
    • username: il tuo nome utente IBM Cloud.
    • password: la tua password IBM Cloud.
    • bss_account: l'ID account IBM Cloud che hai richiamato nel passo precedente.
    Corpo per le chiavi API IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: la tua chiave API IBM Cloud.
    • bss_account: l'ID account IBM Cloud che hai richiamato nel passo precedente.
    Corpo per il passcode monouso IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • passcode: il tuo passcode IBM Cloud.
    • bss_account: l'ID account IBM Cloud che hai richiamato nel passo precedente.

    Il seguente esempio mostra l'output per la richiesta API.

    {
    "access_token": "<iam_token>",
    "refresh_token": "<iam_refresh_token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expiration": 1493747503
}

    È possibile trovare il token IAM " IBM Cloud " nel campo " access_token " e il token di aggiornamento nel campo " refresh_token " dell'output dell'API.

  4. Elenca tutti i cluster classici o VPC nel tuo account. Se vuoi eseguire le richieste API Kubernetes su un cluster, assicurati di prendere nota del nome o dell'ID del cluster con cui vuoi lavorare. Richiesta di esempio per elencare i cluster Classic.

    GET https://containers.cloud.ibm.com/global/v2/classic/getClusters
    Intestazione
    Authorization: bearer <iam_token>

    Comando di esempio per elencare i cluster VPC.

    GET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2
    Intestazione
    Authorization: il tuo token di accesso IAM IBM Cloud (bearer <iam_token>).

  5. Consultare la documentazione dell'API IBM Cloud Kubernetes Service per trovare un elenco delle API supportate.

Quando utilizzi l'API per l'automazione, assicurati di basarti sulle risposte dall'API, non i file all'interno di queste risposte. Ad esempio, il file di configurazione Kubernetes relativo al contesto del cluster è soggetto a modifiche; pertanto, non basare l'automazione su contenuti specifici di questo file quando si utilizza la chiamata GET /v1/clusters/{idOrName}/config .

Utilizzo del tuo cluster attraverso l'API Kubernetes

È possibile utilizzare l'API " Kubernetes " per interagire con il proprio cluster all'indirizzo IBM Cloud Kubernetes Service.

Le istruzioni riportate di seguito richiedono che il cluster disponga di un accesso alla rete pubblica per connettersi all'endpoint del servizio cloud pubblico del master di Kubernetes.

  1. Segui i passaggi descritti nella guida " Automazione delle distribuzioni dei cluster tramite l'API " per recuperare il token di accesso IAM IBM Cloud, la chiave API IBM Cloud, l'ID del cluster in cui desideri eseguire le richieste API Kubernetes e la regione IBM Cloud Kubernetes Service in cui si trova il tuo cluster.

  2. Recuperare un ID IAM, un accesso IAM e un token di aggiornamento IAM di IBM Cloud utilizzando la chiave API IBM Cloud. Nell'output dell'API, è possibile trovare il token ID IAM nel campo id_token, il token di accesso IAM nel campo access_token e il token di aggiornamento IAM nel campo refresh_token.

    POST https://iam.cloud.ibm.com/identity/token
    Intestazione
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic a3ViZTprdWJl a3ViZTprdWJl corrisponde all'autorizzazione codificata secondo lo standard " URL " per il nome utente kube e la password kube.
    Corpo
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: la tua chiave API IBM Cloud.

    Il seguente esempio mostra l'output dalla richiesta API precedente.

    {
"access_token": "<iam_access_token>",
"id_token": "<iam_id_token>",
"refresh_token": "<iam_refresh_token>",
"token_type": "Bearer",
"expires_in": 3600,
"expiration": 1553629664,
"refresh_token_expiration": 1761334993,
"scope": "ibm openid containers-kubernetes"
}

    In alternativa, utilizzando il comando CLI ibmcloud ks cluster config --cluster <cluster_name> --output json si visualizzeranno i dati id_token e refresh_token.

  3. Prima di poter accedere al cluster con la propria identità attuale, è necessario eseguire la seguente richiesta.

    POST https://containers.cloud.ibm.com/global/v2/applyRBAC
    Intestazione
    Authorization: bearer <TOKEN> Il token di accesso IAM di IBM Cloud
    Corpo
    cluster: <cluster_name_or_ID>

  4. Si noti che la sincronizzazione di RBAC è asincrona, quindi eseguire la richiesta seguente fino a quando la sincronizzazione non è avvenuta.

    GET https://containers.cloud.ibm.com/global/v2/getRBACStatus?cluster=<cluster_name_or_ID>

-H "Autorizzazione: ${BEARER2} " ``` Header : Authorization: bearer <TOKEN> Your IBM Cloud IAM access token

Example response. Ensure the output shows `synchronized:true`.

```json {: screen}
{"synchronized":true,"error":false}
```

  1. Recuperare l' URL e dell'endpoint di servizio predefinito per il master dell' Kubernetes, utilizzando il token di accesso IAM e il nome o l'ID del cluster. Puoi trovare l' URL nell'masterURL dell'output della tua API.

    Se è abilitato solo l'endpoint del servizio cloud pubblico o solo l'endpoint del servizio cloud privato per il tuo cluster, tale endpoint viene elencato per masterURL. Se entrambi gli endpoint del servizio cloud pubblico e privato sono abilitati per il tuo cluster, l'endpoint del servizio cloud pubblico viene elencato per impostazione predefinita per masterURL. Per utilizzare invece l'endpoint del servizio cloud privato, individuare URL nel campo privateServiceEndpointURL dell'output.

    GET https://containers.cloud.ibm.com/global/v2/getCluster?cluster=<cluster_name_or_ID>
    Intestazione
    • Authorization: il tuo token di accesso IBM Cloud IAM.
    Percorso
    • <cluster_name_or_ID>: il nome o l'ID del tuo cluster che hai richiamato con l'API GET https://containers.cloud.ibm.com/global/v2/classic/getClusters o GET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2 in Automazione delle distribuzioni del cluster con l'API.

    Il seguente esempio mostra l'output per una richiesta dell'endpoint del servizio cloud pubblico.

    ...
"etcdPort": "31593",
"masterURL": "https://c2.us-south.containers.cloud.ibm.com:30422",
"ingress": {
    ...}

    Il seguente esempio mostra l'output per una richiesta di endpoint del servizio cloud privato.

    ...
"etcdPort": "31593",
"masterURL": "https://c2.private.us-south.containers.cloud.ibm.com:30422",
"ingress": {
    ...}

  2. Per utilizzare un endpoint del servizio cloud privato, devi prima esporre l'endpoint del servizio cloud privato utilizzando un IP del programma di bilanciamento del carico instradabile dalla tua connessione VPN nella rete privata.

  3. Esegui le richieste API Kubernetes per il tuo cluster utilizzando il token ID IAM che hai richiamato in precedenza. Ad esempio, elenca la versione Kubernetes eseguita nel tuo cluster.

    Se hai abilitato la verifica del certificato SSL nel framework di test API, assicurati di disabilitare questa funzione.

    GET <masterURL>/api
    Intestazione
    • Authorization: bearer <id_token>
    Percorso
    • <masterURL>: L'endpoint di servizio del master di Kubernetes che hai recuperato nel passaggio precedente.

    Il seguente esempio mostra l'output della richiesta API precedente.

    {
	"kind": "APIVersions",
	"versions": [
		"v1"
	],
	"serverAddressByClientCIDRs": [
		{
			"clientCIDR": "0.0.0.0/0",
			"serverAddress": "xxx.xx.x.x:xxxx"
		}
	]
 }

  4. Consulta la documentazione dell'API di Kubernetes per trovare un elenco delle API supportate dall'ultima versione di Kubernetes. Assicurati di utilizzare la documentazione API che corrisponde alla versione Kubernetes del tuo cluster. Se non utilizzi l'ultima versione di Kubernetes, aggiungi la tua versione alla fine dell'URL URL. Ad esempio, per accedere alla documentazione API per la versione 1.12, aggiungi v1.12.

Aggiornamento dei token di accesso IAM con l'API

Ogni token di accesso IBM Cloud IAM (Identity and Access Management) che viene emesso tramite API scade dopo un'ora. Per garantire l'accesso all'API IBM Cloud devi aggiornare regolarmente il tuo token di accesso.

Prima di iniziare, assicurarsi di avere una chiave API IBM Cloud da usare per richiedere un nuovo token di accesso.

Se si desidera ottenere un nuovo token IAM IBM Cloud, procedere come segue.

  1. Generare un nuovo token di accesso IAM IBM Cloud utilizzando la chiave API IBM Cloud.

    POST https://iam.cloud.ibm.com/identity/token
    Intestazione
    • Content-Type: application/x-www-form-urlencoded
    Corpo
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: la tua chiave API IBM Cloud.

    Il seguente esempio mostra l'output della richiesta API precedente.

    {
    "access_token": "<iam_token>",
    "refresh_token": "<iam_refresh_token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expiration": 1493747503,
    "scope": "ibm openid"
}

    Puoi trovare il tuo nuovo token IAM " IBM Cloud " nel campo " access_token " dell'output dell'API.

  2. Continua a utilizzare la documentazione dell'API " IBM Cloud Kubernetes Service " utilizzando il token ottenuto nel passaggio precedente.