Configuration de l'API

Vous pouvez utiliser l'API IBM Cloud® Kubernetes Service pour créer et gérer 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 IBM Cloud Kubernetes Service 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 qui vous permettent de créer des 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 IBM Cloud Kubernetes Service 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 IBM Cloud Kubernetes Service v2 pour gérer vos ressources d'infrastructure IBM Cloud, telles que les nœuds worker, pour les clusters Kubernetes et de VPC Red Hat OpenShift de la communauté.
API Kubernetes
API v1 : pour utiliser l'API Kubernetes pour gérer les ressources Kubernetes dans le cluster, telles que les pods ou les espaces de nom, voir Utilisation de votre cluster en utilisant l'API Kubernetes.
API v2 : identique à v1 ; voir Utilisation de votre cluster en utilisant l'API Kubernetes.
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 IBM Cloud Kubernetes Service pour automatiser la création, le déploiement et la gestion de vos clusters Kubernetes.

L'API IBM Cloud Kubernetes Service requiert de fournir des informations d'en-tête dans votre demande d'API, lesquelles peuvent varier selon l'API à utiliser. Pour déterminer quelles informations d'en-tête sont nécessaires pour votre API, consultez la documentation de l'API IBM Cloud Kubernetes Service.

Pour s'authentifier auprès d'IBM Cloud Kubernetes Service, 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érez une clé API IBM Cloud: au lieu d’utiliser votre nom d’utilisateur et votre mot de passe IBM Cloud, vous pouvez utiliser des clés API IBM Cloud IBM Cloud. Ces clés 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 menus, 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 pouvez trouver le jeton IAM IBM Cloud dans le champ access_token de la sortie de votre 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 la sortie de votre 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 d'autres comptes, connectez-vous à ce compte et créez une clé API IBM Cloud associée à 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 IBM Cloud dans le champ et access_token le jeton d'actualisation dans le refresh_token champ de la sortie de votre API.

  4. Répertoriez tous les clusters classiques ou VPC de votre compte. Si vous souhaitez exécuter des demandes d'API Kubernetes sur un cluster, prenez soin de noter le nom ou l'ID du cluster que vous souhaitez utiliser. 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 IBM Cloud Kubernetes Service 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.

Utilisation de votre cluster à l'aide de l'API Kubernetes

Vous pouvez utiliser l'API Kubernetes pour interagir avec votre cluster dans IBM Cloud Kubernetes Service.

Les instructions ci-après requièrent un accès de réseau public dans votre cluster pour établir une connexion au noeud final de service cloud public de votre maître Kubernetes.

  1. Suivez les étapes décrites dans la section Automatisation des déploiements de clusters à l’aide de l’API pour récupérer votre jeton d’accès IAM IBM Cloud, votre clé API IBM Cloud, l’ID du cluster sur lequel vous souhaitez exécuter les requêtes API Kubernetes, ainsi que la région IBM Cloud Kubernetes Service où se trouve votre cluster.

  2. Récupérer un ID IAM IBM Cloud, un accès IAM et un jeton de rafraîchissement IAM à l'aide de la clé API IBM Cloud. Dans le résultat de votre API, vous trouverez le jeton d'identification IAM dans le id_token champ, le jeton d'accès IAM dans le access_token champ et le jeton d'actualisation IAM dans le refresh_token champ.

    POST https://iam.cloud.ibm.com/identity/token
    En-tête
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic a3ViZTprdWJl a3ViZTprdWJl correspond à l'autorisation codée en URL pour le nom d'utilisateur et kube le mot de passe kube.
    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_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"
}

    Une autre solution consiste à utiliser la commande CLI ibmcloud ks cluster config --cluster <cluster_name> --output json pour afficher les pages id_token et refresh_token.

  3. Avant de pouvoir accéder à votre cluster avec votre identité actuelle, vous devez exécuter la requête suivante.

    POST https://containers.cloud.ibm.com/global/v2/applyRBAC
    En-tête
    Authorization: bearer <TOKEN> Votre jeton d'accès IAM IBM Cloud
    Corps
    cluster: <cluster_name_or_ID>

  4. Notez que la synchronisation RBAC est asynchrone, donc exécutez la requête suivante jusqu'à ce qu'elle soit synchronisée.

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

-H "Autorisation : ${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. Extrayez l'URL du noeud final de service par défaut pour votre maître Kubernetes à l'aide du jeton d'accès IAM et du nom ou de l'ID de votre cluster. L'URL figure dans la zone masterURL de la sortie de votre API.

    Si seul le noeud final de service cloud public ou le noeud final de service cloud privé est activé pour votre cluster, ce noeud final est répertorié pour masterURL. Si les noeuds finaux de service cloud public et de service cloud privé sont activés pour votre cluster, le noeud final de service public est répertorié par défaut pour masterURL. Pour utiliser le noeud final de service cloud privé à la place, recherchez l'URL dans la zone privateServiceEndpointURL de la sortie.

    GET https://containers.cloud.ibm.com/global/v2/getCluster?cluster=<cluster_name_or_ID>
    En-tête
    • Authorization : votre jeton d'accès IBM Cloud IAM.
    Voie
    • <cluster_name_or_ID> : nom ou ID de votre cluster que vous avez extrait avec l'API GET https://containers.cloud.ibm.com/global/v2/classic/getClusters ou GET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2 dans Automatisation des déploiements de cluster avec l'API.

    L'exemple ci-après illustre la sortie d'une demande de noeud final de service cloud public.

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

    L'exemple ci-après illustre la sortie d'une demande de noeud final de service de cloud privé.

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

  2. Pour utiliser un nœud final de service de cloud privé, vous devez d'abord exposer ce nœud à l'aide d'une adresse IP d'équilibreur de charge qui est routable à partir de votre connexion VPN vers le réseau privé.

  3. Exécutez des demandes d'API Kubernetes sur votre cluster à l'aide du jeton d'ID IAM que vous avez extrait précédemment. Par exemple, répertoriez la version de Kubernetes qui s'exécute dans votre cluster.

    Si vous avez activé la vérification de certificat SSL dans votre structure de test d'API, prenez soin de désactiver cette fonction.

    GET <masterURL>/api
    En-tête
    • Authorization: bearer <id_token>
    Voie
    • <masterURL> : nœud final de service de votre maître Kubernetes que vous avez extrait à l'étape précédente.

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

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

  4. Consultez la documentation de l'API Kubernetes pour trouver la liste des API prises en charge par la dernière version Kubernetes. Prenez soin d'utiliser la documentation d'API correspondant à la version Kubernetes de votre cluster. Si vous n'utilisez pas la dernière version de Kubernetes, ajoutez votre version à la fin de l'URL. Par exemple, pour accéder à la documentation d'API de la version 1.12, ajoutez v1.12.

Actualisation des jetons d'accès IAM via 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 la sortie de votre API.

  2. Poursuivez votre travail avec la documentation de l'API IBM Cloud Kubernetes Service en utilisant le jeton obtenu à l'étape précédente.