Configuration de l'API

Red Hat® OpenShift® on IBM Cloud® partage la même interface de programmation (API) qu'IBM Cloud Kubernetes Service, par conséquent, vous pouvez recourir aux mêmes méthodes pour créer et gérer de manière cohérente vos clusters de communauté Kubernetes ou Red Hat OpenShift. Pour utiliser l'interface de ligne de commande, voir Configuration de l'interface de ligne de commande.

A propos de l'API

L'API Red Hat OpenShift on IBM Cloud automatise la mise à disposition et la gestion des ressources d'infrastructure IBM Cloud pour vos clusters de sorte que vos applications disposent des ressources de calcul, de mise en réseau et de stockage dont elles ont besoin pour servir vos utilisateurs.

L'API prend en charge les différents fournisseurs d'infrastructure disponibles pour la création de clusters. Pour plus d'informations, voir la présentation du fournisseur d'infrastructure.

Vous pouvez utiliser l'API version deux (v2) pour gérer des clusters classiques et des clusters de VPC. L'API v2 est conçue pour éviter, dans la mesure du possible, de rompre une fonctionnalité existante. Toutefois, prenez soin de passer en revue les différences entre l'API v1 et l'API v2 qui sont présentées ci-après.

Préfixe de noeud final d'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
Documents de référence d'API
v1 et v2 API
v3 API.
Style d'architecture d'API
API v1 : Representational State Transfer (REST) qui se concentre sur les ressources avec lesquelles vous interagissez via des méthodes HTTP telles que GET, POST, PUT, PATCH et DELETE.
API v2 : appels de procédure distante (RPC) qui mettent l'accent sur les actions uniquement via les méthodes HTTP GET et POST.
Plateformes de conteneur prises en charge
API v1 : Utilisez l'API Red Hat OpenShift on IBM Cloud pour gérer vos ressources d'infrastructure IBM Cloud , telles que les nœuds worker, pour les clusters Kubernetes et Red Hat OpenShift de la communauté.
API v2 : Utilisez l'API Red Hat OpenShift on IBM Cloud v2 pour gérer vos ressources d'infrastructure IBM Cloud , telles que les nœuds worker, pour les clusters Kubernetes et les VPC Red Hat OpenShift de communauté.
API Red Hat OpenShift
v1 API : Pour utiliser l'API Red Hat OpenShift afin de gérer les ressources Red Hat OpenShift et Kubernetes au sein du cluster, telles que les pods ou les espaces de noms, vous devez vous connecter en échangeant une clé d'API IBM Cloud contre un jeton d'accès Red Hat OpenShift. Pour plus d'informations, voir Utilisation d'une clé d'API pour se connecter à des clusters.
API v2 : Identique à v1; voir Utilisation d'une clé d'API pour se connecter à des clusters.
API prises en charge par type d'infrastructure
API v1 : classic
API v2 : vpc et classic
  • Le fournisseur vpc est conçu pour prendre en charge plusieurs sous-fournisseurs VPC. Le sous-fournisseur VPC pris en charge est vpc-gen2, qui correspond à un cluster de VPC pour des ressources de calcul Génération 2.
  • Un paramètre de chemin figure dans l'URL des demandes propres aux fournisseurs, par exemple v2/vpc/createCluster. Certaines API ne sont disponibles que pour un fournisseur en particulier, par exemple GET vlan pour un fournisseur classique ou GET vpcs pour un fournisseur VPC.
  • Les demandes qui ne dépendent pas des fournisseurs peuvent inclure un paramètre de corps propre aux fournisseurs que vous spécifiez, généralement au format JSON, par exemple, {"provider": "vpc"}, si vous souhaitez renvoyer des réponses uniquement pour le fournisseur spécifié.
Réponses GET
API v1 : la méthode GET pour une collection de ressources (telle que GET v1/clusters) renvoie les mêmes détails pour chaque ressource de la liste en tant que méthode GET pour une ressource individuelle (telle que GET v1/clusters/{idOrName}).
API v2 : pour renvoyer des réponses plus rapidement, la méthode v2 GET pour une collection de ressources (telle que GET v2/clusters) renvoie uniquement un sous-ensemble d'informations détaillées dans une méthode GET pour une ressource individuelle (telle que GET v2/clusters/{idOrName}). Certaines réponses de liste incluent une propriété de fournisseurs afin de déterminer si l'élément renvoyé s'applique à l'infrastructure classique ou à l'infrastructure VPC. Par exemple, la liste GET zones renvoie certains résultats, tels que mon01, qui sont disponibles uniquement dans le fournisseur d'infrastructure classique,, tandis que d'autres résultats, tels que us-south-01, sont disponibles uniquement dans le fournisseur d'infrastructure VPC.
Réponses de cluster, de noeud worker et de pool de noeuds worker
API v1 : les réponses incluent uniquement les informations spécifiques au fournisseur d'infrastructure classique, telles que les VLAN dans le cluster GET et les réponses de worker.
API v2 : les informations renvoyées varient en fonction du fournisseur d'infrastructure. Pour ces réponses propres aux fournisseurs, vous pouvez spécifier le fournisseur dans votre demande. Par exemple, les clusters VPC ne renvoient pas les informations VLAN, car ils n'ont pas de VLAN. En revanche, ils renvoient des informations réseau CIDR et de sous-réseau.

Automatisation des déploiements de cluster à l'aide de l'API

Vous pouvez utiliser l'API Red Hat OpenShift on IBM Cloud pour automatiser la création, le déploiement et la gestion de vos clusters Red Hat OpenShift.

L'API Red Hat OpenShift on IBM Cloud requiert de fournir des informations d'en-tête dans votre demande d'API, lesquelles peuvent varier selon l'API à utiliser. Pour déterminer les informations d'en-tête nécessaires à votre API, consultez la documentation de l'API Red Hat OpenShift on IBM Cloud.

Pour s'authentifier auprès de Red Hat OpenShift on IBM Cloud, vous devez fournir un jeton IBM Cloud IAM (Identity and Access Management) qui est généré avec vos données d'identification IBM Cloud et qui comprend l'ID du compte IBM Cloud dans lequel a été créé le cluster. Selon votre mode d'authentification auprès d'IBM Cloud, vous pouvez choisir parmi les options suivantes pour automatiser la création de votre jeton IBM Cloud IAM.

ID non fédéré
  • Générer une clé API IBM Cloud: Au lieu d'utiliser le nom d'utilisateur et le mot de passe de IBM Cloud, vous pouvez utiliser les clés API de IBM Cloud. IBM Cloud Les clés API dépendent du compte IBM Cloud pour lequel elles sont générées. Vous ne pouvez pas combiner votre clé d'API IBM Cloud avec un ID de compte différent dans le même jeton IAM IBM Cloud. Pour accéder aux clusters créés avec un compte autre que celui sur lequel votre clé d'API IBM Cloud est basée, vous devez vous connecter au compte pour générer une nouvelle clé d'API.
  • Nom d'utilisateur et mot de passe IBM Cloud : vous pouvez suivre la procédure indiquée dans cette rubrique pour automatiser complètement la création de votre jeton d'accès IBM Cloud IAM.
ID fédéré
  • Générez une clé d'API IBM Cloud Clé d'API : les clés d'API IBM Cloud dépendent du compte IBM Cloud pour lequel elles sont générées. Vous ne pouvez pas combiner votre clé d'API IBM Cloud avec un ID de compte différent dans le même jeton IAM IBM Cloud. Pour accéder aux clusters créés avec un compte autre que celui sur lequel votre clé d'API IBM Cloud est basée, vous devez vous connecter au compte pour générer une nouvelle clé d'API.
  • Utilisez un mot de passe à utilisation unique : si vous vous authentifiez dans IBM Cloud à l'aide d'un mot de passe à utilisation unique, vous ne pouvez pas automatiser entièrement la création de votre jeton IBM Cloud IAM, car l'extraction de votre mot de passe à utilisation unique nécessite une interaction manuelle avec votre navigateur Web. Pour automatiser complètement la création de votre jeton IBM Cloud IAM, vous devez créer une clé d'API IBM Cloud à la place.
  • Clé API : Pour générer votre IBM Cloud Clé API, procédez comme suit.
    1. Dans la barre de menu, cliquez sur Gérer > Accès (IAM).
    2. Cliquez sur la page Utilisateurs, puis sélectionnez-vous.
    3. Dans le panneau Clés d'API, cliquez sur Créer une clé d'API IBM Cloud.
    4. Entrez un Nom et une Description pour la clé d'API et cliquez sur Créer.
    5. Cliquez sur Afficher pour voir la clé d'API qui a été générée pour vous.
    6. Copiez la clé d'API pour pouvoir l'utiliser pour récupérer votre nouveau jeton d'accès IBM Cloud IAM.

  1. Créez votre jeton d'accès IBM Cloud IAM. Les informations de corps contenues dans votre demande varient en fonction de la méthode d'authentification IBM Cloud que vous utilisez.

    POST https://iam.cloud.ibm.com/identity/token
    En-tête
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic Yng6Yng= où Yng6Yng= est égal à l'autorisation codée dans l'URL pour le nom d'utilisateur bx et le mot de passe bx.
    Corps pour le nom d'utilisateur et le mot de passe IBM Cloud
    • grant_type: password
    • username : votre nom d'utilisateur IBM Cloud.
    • password : votre mot de passe IBM Cloud.
    Corps pour les clés d'API IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey : votre clé d'API IBM Cloud
    Corps pour le code d'accès à usage unique IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • passcode : votre code d'accès à usage unique IBM Cloud. Exécutez la commande ibmcloud login --sso et suivez les instructions de la sortie de l'interface de ligne de commande pour extraire votre code d'accès à usage unique en utilisant votre navigateur Web.

    L'exemple ci-après illustre la sortie de la demande précédente.

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

    Vous trouverez le jeton IAM de IBM Cloud dans le champ access_token de votre sortie API. Notez la valeur du jeton IBM Cloud IAM pour extraire des informations d'en-tête supplémentaires dans les étapes suivantes.

  2. Extrayez l'ID du compte IBM Cloud que vous souhaitez utiliser. Remplacez TOKEN par le jeton IAM IBM Cloud que vous avez récupéré dans le champ access_token de votre sortie API à l'étape précédente. Dans votre sortie d'API, l'ID de votre compte IBM Cloud se trouve dans la zone resources.metadata.guid.

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

    L'exemple ci-après illustre la sortie de la demande précédente.

    {
"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. Générez un nouveau jeton IBM Cloud IAM comprenant vos données d'identification IBM Cloud et l'ID du compte que vous souhaitez utiliser.

    Si vous utilisez une clé d'API IBM Cloud, vous devez utiliser l'ID du compte IBM Cloud pour lequel la clé d'API a été créée. Pour accéder aux clusters dans d'autres comptes, connectez-vous à ce compte et créez une clé API IBM Cloud basée sur ce compte.

    POST https://iam.cloud.ibm.com/identity/token
    En-tête
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic Yng6Yng= où Yng6Yng= est égal à l'autorisation codée dans l'URL pour le nom d'utilisateur bx et le mot de passe bx.
    Corps pour le nom d'utilisateur et le mot de passe IBM Cloud
    • grant_type: password
    • username : votre nom d'utilisateur IBM Cloud.
    • password : votre mot de passe IBM Cloud.
    • bss_account : ID de compte IBM Cloud que vous avez extrait lors de l'étape précédente.
    Corps pour les clés d'API IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey : votre clé d'API IBM Cloud
    • bss_account : ID de compte IBM Cloud que vous avez extrait lors de l'étape précédente.
    Corps pour le code d'accès à usage unique IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • passcode : votre code d'accès IBM Cloud.
    • bss_account : ID de compte IBM Cloud que vous avez extrait lors de l'étape précédente.

    L'exemple ci-après illustre la sortie de la demande d'API.

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

    Vous trouverez le jeton IAM de IBM Cloud dans le champ access_token et le jeton de rafraîchissement dans le champ refresh_token de votre sortie API.

  4. Répertoriez tous les clusters classiques ou VPC de votre compte. Exemple de demande d'affichage de la liste des clusters classiques.

    GET https://containers.cloud.ibm.com/global/v2/classic/getClusters
    En-tête
    Authorization: bearer <iam_token>

    Exemple de commande permettant de répertorier les clusters de VPC.

    GET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2
    En-tête
    Authorization : jeton d'accès IBM Cloud IAM (bearer <iam_token>).

  5. Consultez la documentation de l'API Red Hat OpenShift on IBM Cloud pour obtenir la liste des API prises en charge.

Lorsque vous utilisez l'API à des fins d'automatisation, appuyez-vous sur les réponses de l'API, et non pas sur les fichiers contenus dans ces réponses. Par exemple, le fichier de configuration de Kubernetes pour votre contexte de cluster étant sujet à des modification, ne créez pas d'automatisation en fonction d'un contenu spécifique de ce fichier lorsque vous utilisez l'appel GET /v1/clusters/{idOrName}/config.

Actualiser les jetons d'accès IAM avec l'API

Chaque jeton d'accès IBM Cloud IAM (Identity and Access Management) émis via l'API expire au bout d'une heure. Vous devez actualiser régulièrement votre jeton d'accès pour garantir l'accès à l'API IBM Cloud.

Avant de commencer, assurez-vous que vous disposez d'une clé API IBM Cloud que vous pouvez utiliser pour demander un nouveau jeton d'accès.

Procédez comme suit si vous souhaitez obtenir un nouveau jeton IAM IBM Cloud.

  1. Générez un nouveau jeton d'accès IAM IBM Cloud en utilisant la clé API IBM Cloud.

    POST https://iam.cloud.ibm.com/identity/token
    En-tête
    • Content-Type: application/x-www-form-urlencoded
    Corps
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: votre clé d'API IBM Cloud

    L'exemple ci-après illustre la sortie de la demande d'API précédente.

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

    Vous trouverez votre nouveau jeton IAM IBM Cloud dans le champ access_token de votre sortie API.

  2. Continuez à travailler avec la documentation de l'API Red Hat OpenShift on IBM Cloud en utilisant le jeton de l'étape précédente.