Configurazione dell'API

Red Hat® OpenShift® on IBM Cloud® condivide la stessa interfaccia di programmazione delle applicazioni (API) di IBM Cloud Kubernetes Service, consentendo così di utilizzare gli stessi metodi per creare e gestire in modo coerente i cluster della propria community su Kubernetes o Red Hat OpenShift. Per utilizzare la CLI, vedi Configurazione della CLI.

Informazioni sull'API

L'API di Red Hat OpenShift on IBM Cloud 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 di tipo " HTTP ", quali GET, POST, PUT, PATCH e DELETE.
v2 API: Chiamate di procedura remota ( RPC ) incentrate esclusivamente sulle azioni eseguibili tramite i metodi GET, POST e HTTP.
Piattaforme del contenitore supportate
v1 API: Utilizza l'API " Red Hat OpenShift on IBM Cloud " per gestire le risorse dell'infrastruttura di IBM Cloud, come i nodi di lavoro, per sia i cluster " Kubernetes " che quelli " Red Hat OpenShift ".
v2 API: Utilizza l’API “ Red Hat OpenShift on IBM Cloud v2 ” per gestire le risorse dell’infrastruttura di IBM Cloud, come i nodi di lavoro, per **sia i cluster VPC della community Kubernetes che quelli di Red Hat OpenShift **.
API Red Hat OpenShift
v1: per utilizzare l'API Red Hat OpenShift per gestire Red Hat OpenShift e le risorse Kubernetes all'interno del cluster, come i pod o gli spazi dei nomi, devi accedere scambiando una chiave API IBM Cloud per un Red Hat OpenShift Vedi Utilizzo di una chiave API per accedere ai cluster.
API v2: uguale a v1; vedi Utilizzo di una chiave API per accedere ai cluster.
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 seconda generazione.
  • 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, ad esempio {"provider": "vpc"}, se si desidera ottenere risposte solo per il provider specificato.
GET risposte
v1 API: Il metodo GET applicato a un insieme di risorse (ad esempio GET v1/clusters) restituisce gli stessi dettagli per ciascuna risorsa dell'elenco forniti dal metodo GET applicato a 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, come le VLAN in un cluster 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

È possibile utilizzare l'API di Red Hat OpenShift on IBM Cloud per automatizzare la creazione, la distribuzione e la gestione dei propri cluster Red Hat OpenShift.

L'API Red Hat OpenShift on IBM Cloud richiede informazioni di intestazione che devi fornire nella tua richiesta API e che possono variare in base all'API che vuoi utilizzare. Per determinare quali informazioni di intestazione sono necessarie per la tua API, consulta la documentazione dell'API Red Hat OpenShift on IBM Cloud.

Per l'autenticazione con Red Hat OpenShift on IBM Cloud, 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'uso del nome utente e della password di IBM Cloud, è possibile usare 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 puoi automatizzare completamente la creazione del tuo 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. 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 Red Hat OpenShift on IBM Cloud 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.

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 lavorare con la documentazione API Red Hat OpenShift on IBM Cloud utilizzando il token del passaggio precedente.