Configurazione dell'API

Red Hat® OpenShift® on IBM Cloud® condivide la stessa interfaccia di programmazione delle applicazioni (API) di IBM Cloud Kubernetes Service, in modo da poter utilizzare gli stessi metodi per creare e gestire in modo coerente i cluster della comunità 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: Trasferimento di stato rappresentativo (REST) che si concentra sulle risorse con cui si interagisce attraverso i metodi HTTP come GET, POST, PUT, PATCH e DELETE.
v2 API: Chiamate di procedura remota ( RPC ) che si concentrano sulle azioni attraverso i soli metodi GET e POST HTTP.
Piattaforme del contenitore supportate
v1 API: Utilizzare l'API Red Hat OpenShift on IBM Cloud per gestire le risorse dell'infrastruttura IBM Cloud, come i nodi worker, per **sia la comunità Kubernetes che i cluster Red Hat OpenShift **.
v2 API: Utilizzare l'API Red Hat OpenShift on IBM Cloud v2 per gestire le risorse dell'infrastruttura IBM Cloud, come i nodi worker, per i cluster VPC Kubernetes e Red Hat OpenShift comunitari.
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 sottoprovider 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 neutre rispetto al provider possono includere un parametro del corpo specifico del provider che viene specificato dall'utente, di solito in JSON, come {"provider": "vpc"}, se si desidera restituire risposte solo per il provider specificato.
GET risposte
v1 API: Il metodo GET per un insieme di risorse (come GET v1/clusters) restituisce gli stessi dettagli per ogni risorsa dell'elenco come il metodo GET per una risorsa individuale (come GET v1/clusters/{idOrName}).
v2 API: Per restituire le risposte più velocemente, il metodo v2 GET per un insieme di risorse (come GET v2/clusters) restituisce solo un sottoinsieme di informazioni che sono dettagliate in un metodo GET per una singola risorsa (come 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 le informazioni specifiche del provider dell'infrastruttura classica, come le VLAN nel cluster GET e le risposte dei lavoratori.
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 Red Hat OpenShift on IBM Cloud per automatizzare la creazione, la distribuzione e la gestione dei 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 combinare la chiave API IBM Cloud con un altro ID account nello stesso token IAM 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 combinare la chiave API IBM Cloud con un altro ID account nello stesso token IAM 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.
  • Utilizzare un codice di accesso unico: Se ci si autentica con IBM Cloud utilizzando un codice di accesso unico, non è possibile automatizzare completamente la creazione del token IAM IBM Cloud perché il recupero del codice di accesso unico 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= equivale all'autorizzazione codificata 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"
}

    Il token IAM IBM Cloud si trova nel campo access_token dell'output 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. Sostituire TOKEN con il token IAM IBM Cloud recuperato dal campo access_token dell'output 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 in altri account, accedere a questo account e creare una chiave API IBM Cloud basata su questo account.

    POST https://iam.cloud.ibm.com/identity/token
    Intestazione
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic Yng6Yng= dove Yng6Yng= equivale all'autorizzazione codificata 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
}

    Il token IAM IBM Cloud si trova nel campo access_token e il token di aggiornamento nel campo refresh_token dell'output 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 per il contesto del cluster è soggetto a modifiche, quindi non costruire l'automazione in base ai contenuti specifici di questo file quando si usa 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"
}

    Il nuovo token IAM di IBM Cloud si trova nel campo access_token dell'output API.

  2. Continua a lavorare con la documentazione API Red Hat OpenShift on IBM Cloud utilizzando il token del passaggio precedente.