API einrichten
Sie können die IBM Cloud® Kubernetes Service-API zum Erstellen und Verwalten Ihrer Community-Kubernetes-Cluster oder Red Hat OpenShift-Cluster verwenden. Informationen zur Verwendung der Befehlszeilenschnittstelle (CLI) finden Sie unter Befehlszeilenschnittstelle einrichten.
Informationen zur API
Die IBM Cloud Kubernetes Service-API automatisiert die Bereitstellung und Verwaltung von IBM Cloud-Infrastrukturressourcen für Ihre Cluster, sodass Ihre Apps über die entsprechenden Datenverarbeitungs-, Netz- und Speicherressourcen verfügen, um Ihren Benutzern dienlich sein zu können.
Die API unterstützt die verschiedenen Infrastrukturanbieter, die Ihnen zum Erstellen von Clustern zur Verfügung stehen. Weitere Informationen finden Sie unter Infrastruktur-Provider-Übersicht.
Mit der API der Version 2 (v2) können Sie sowohl klassische als auch VPC-Cluster verwalten. Version 2 (v2) der API wurde dazu konzipiert, um nach Möglichkeit eine Beeinträchtigung der bestehenden Funktionalität zu vermeiden.
Stellen Sie jedoch sicher, dass Sie sich mit den folgenden Unterschieden zwischen der API v1 und der API v2 vertraut machen.
- Präfix für API-Endpunkt
- v1-API:
https://containers.cloud.ibm.com/global/v1 - v2-API:
https://containers.cloud.ibm.com/global/v2 - v3 API:
https://containers.cloud.ibm.com/global/v3 - API-Referenzdokumente
- v1 und v2 API
- v3 API.
- Stil der API-Architektur
- v1-API: REST (Representational State Transfer) mit Schwerpunkt auf Ressourcen, mit denen Sie über HTTP-Methoden wie
GET,POST,PUT,PATCHundDELETEinteragieren. - v2-API: RPCs (Remote Procedure Calls) mit Schwerpunkt auf Aktionen, die ausschließlich über
GET- undPOST-HTTP-Methoden erfolgen. - Unterstützte Containerplattformen
- v1-API: Verwenden Sie die IBM Cloud Kubernetes Service-API zum Verwalten Ihrer IBM Cloud-Infrastrukturressourcen (z. B. Workerknoten) für Community-Kubernetes- und Red Hat OpenShift-Cluster.
- v2-API: Verwenden Sie die IBM Cloud Kubernetes Service
v2-API zum Verwalten Ihrer IBM Cloud-Infrastrukturressourcen (z. B. Workerknoten) für Community-Kubernetes- und Red Hat OpenShift-VPC-Cluster. - Kubernetes-API
- v1-API: Informationen zum Verwalten von Kubernetes-Ressourcen im Cluster (z. B. Pods oder Namensbereiche) mithilfe der Kubernetes-API finden Sie in Unter Verwendung der Kubernetes-API mit Ihrem Cluster arbeiten.
- v2-API: Wie
v1. Informationen finden Sie in Unter Verwendung der Kubernetes-API mit Ihrem Cluster arbeiten. - Unterstützte APIs nach Infrastrukturtyp
- v1-API:
classic - v2-API:
vpcundclassic- Der Provider
vpcist für die Unterstützung mehrerer VPC-Provider konzipiert. Der unterstützte Subprovider istvpc-gen2, was einem VPC-Cluster mit Rechenressourcen der 2. Generation entspricht. - Providerspezifische Anforderungen weisen einen Pfadparameter in der URL auf, wie zum Beispiel bei
v2/vpc/createCluster. Manche APIs stehen nur einem bestimmten Provider zur Verfügung, wie zum BeispielGET vlanfür die klassische Infrastruktur oderGET vpcsfür VPC. - Providerunabhängige Anforderungen können einen providerspezifischen Hauptteilparameter enthalten, den Sie (in der Regel in JSON) angeben, zum Beispiel
{"provider": "vpc"}, wenn nur für den angegebenen Provider Antworten zurückgeben möchten.
- Der Provider
GET-Antworten- v1-API: Die
GET-Methode für eine Sammlung von Ressourcen (z. B.GET v1/clusters) gibt für jede Ressource in der Liste die gleichen Details zurück wie eineGET-Methode für eine einzelne Ressource (z. B.GET v1/clusters/{idOrName}). - v2-API: Um die Rückgabe von Antworten zu beschleunigen, gibt die v2
GET-Methode für eine Sammlung von Ressourcen (z. B.GET v2/clusters) nur eine Untergruppe der Informationen zurück, die in einerGET-Methode für eine einzelne Ressource (z. B.GET v2/clusters/{idOrName}) angegeben sind. Manche Listenantworten enthalten eine Providereigenschaft, die angibt, ob das zurückgegebene Element für die klassische Infrastruktur oder für eine VPC-Infrastruktur gilt. Die ListeGET zonesgibt zum Beispiel einige Ergebnisse wiemon01zurück, die nur beim Provider der klassischen Infrastruktur verfügbar sind, während andere Ergebnisse wieus-south-01nur bei einem Provider der VPC-Infrastruktur verfügbar sind. - Cluster-, Workerknoten- und Worker-Pool-Antworten
- v1-API: Die Antworten enthalten nur spezifische Informationen für den Provider der klassischen Infrastruktur (z. B. die VLANs in
GET-Cluster- und -Workerantworten. - v2-API: Die zurückgegebenen Informationen variieren je nach Infrastrukturprovider. Für derartige providerspezifische Antworten können Sie den Provider in Ihrer Anforderung angeben. Für VPC-Cluster werden beispielsweise keine VLAN-Informationen zurückgegeben, da sie keine VLANs enthalten. Stattdessen geben sie Teilnetz- und CIDR-Netzinformationen zurück.
Clusterbereitstellungen mit der API automatisieren
Mithilfe der IBM Cloud Kubernetes Service-API können Sie die Erstellung, Bereitstellung und Verwaltung Ihrer Kubernetes-Cluster automatisieren.
Die IBM Cloud Kubernetes Service-API benötigt Headerinformationen, die Sie in Ihrer API-Anforderung bereitstellen müssen. Diese können je nach verwendeter API variieren. Um festzustellen, welche Header-Informationen für Ihre API erforderlich sind, lesen Sie die API-Dokumentation unter IBM Cloud Kubernetes Service.
Zur Authentifizierung bei IBM Cloud Kubernetes Service müssen Sie ein IBM Cloud IAM-Token (IAM = Identity and Access Management) angeben, das mit Ihren IBM Cloud-Berechtigungsnachweisen generiert wurde und das die IBM Cloud-Konto-ID umfasst, unter der der Cluster erstellt wurde. Abhängig von der Methode Ihrer Authentifizierung bei IBM Cloud stehen Ihnen die folgenden Optionen zur Automatisierung der Erstellung Ihres IBM Cloud-IAM-Tokens zur Verfügung.
- Nicht föderierte ID
-
- API-Schlüssel für IBM Cloud generieren: Als Alternative zur Verwendung des Benutzernamens und des Passworts von IBM Cloud können Sie API-Schlüssel für IBM Cloud verwenden. API-Schlüssel für IBM Cloud sind an das IBM Cloud-Konto gebunden, für das sie generiert wurden. Sie können Ihren IBM Cloud-API-Schlüssel nicht mit einer anderen Konto-ID im selben IBM Cloud-IAM-Token kombinieren. Um auf Cluster zugreifen zu können, die mit einem anderen Konto als dem Konto erstellt wurden, auf dem der IBM Cloud-API-Schlüssel basiert, müssen Sie sich bei dem Konto anmelden, um einen neuen API-Schlüssel zu generieren.
- IBM Cloud-Benutzername und -Kennwort: Sie können die Schritte in diesem Abschnitt ausführen, um die Erstellung Ihres IBM Cloud-IAM-Zugriffstokens vollständig zu automatisieren.
- Föderierte ID
-
- Einen IBM Cloud-API-Schlüssel generieren: IBM Cloud-API-Schlüssel sind von dem IBM Cloud-Konto abhängig, für das sie erstellt wurden. Sie können Ihren IBM Cloud-API-Schlüssel nicht mit einer anderen Konto-ID im selben IBM Cloud-IAM-Token kombinieren. Um auf Cluster zugreifen zu können, die mit einem anderen Konto als dem Konto erstellt wurden, auf dem der IBM Cloud-API-Schlüssel basiert, müssen Sie sich bei dem Konto anmelden, um einen neuen API-Schlüssel zu generieren.
- Einmalkenncode verwenden: Wenn Sie sich bei IBM Cloud mit einem Einmalkenncode authentifizieren, kann die Erstellung Ihres IBM Cloud-IAM-Tokens nicht vollständig automatisiert werden, da das Abrufen Ihres Einmalkenncodes die manuelle Interaktion mit Ihrem Web-Browser erfordert. Für die vollständige Automatisierung der Erstellung Ihres IBM Cloud-IAM-Tokens müssen Sie daher einen IBM Cloud-API-Schlüssel erstellen.
- API-Schlüssel: Zum Generieren Ihres IBM Cloud API-Schlüssel zu generieren, gehen Sie wie folgt vor.
- Klicken Sie in der Menüleiste auf Verwalten > Zugriff (IAM).
- Klicken Sie auf die Seite Benutzer und wählen Sie Ihren eigenen Eintrag aus.
- Klicken Sie im Fenster API-Schlüssel auf IBM Cloud-API-Schlüssel erstellen.
- Geben Sie einen Namen und eine Beschreibung für Ihren API-Schlüssel ein und klicken Sie auf Erstellen.
- Klicken Sie auf Anzeigen, um den API-Schlüssel anzuzeigen, der für Sie generiert wurde.
- Kopieren Sie den API-Schlüssel, sodass Sie ihn zum Abrufen Ihres neuen IBM Cloud-IAM-Zugriffstokens verwenden können.
-
Erstellen Sie Ihr IBM Cloud-IAM-Zugriffstoken. Die Informationen des Hauptteils, die in Ihre Anforderung eingeschlossen werden, variieren abhängig von der IBM Cloud-Authentifizierungsmethode, die Sie verwenden.
POST https://iam.cloud.ibm.com/identity/token- Überschrift
-
Content-Type: application/x-www-form-urlencodedAuthorization: Basic Yng6Yng=Dabei entsprichtYng6Yng=der als URL codierten Berechtigung für den Benutzernamen bx und das Kennwort bx.
- Hauptteil für IBM Cloud-Benutzername und -Kennwort
-
grant_type: passwordusername: Ihr IBM Cloud-Benutzername.password: Ihr IBM Cloud-Kennwort.
- Hauptteil für IBM Cloud-API-Schlüssel
-
grant_type: urn:ibm:params:oauth:grant-type:apikeyapikey: Ihr IBM Cloud-API-Schlüssel
- Hauptteil für einmaligen IBM Cloud-Kenncode
-
grant_type: urn:ibm:params:oauth:grant-type:passcodepasscode: Ihr einmaliger IBM Cloud-Kenncode. Führen Sie den Befehlibmcloud login --ssoaus und folgen Sie den Anweisungen in der CLI-Ausgabe, um Ihren einmaligen Kenncode unter Verwendung Ihres Web-Browsers abzurufen.
Das folgende Beispiel zeigt die Ausgabe für die vorherige Anforderung.
{ "access_token": "<iam_access_token>", "refresh_token": "<iam_refresh_token>", "token_type": "Bearer", "expires_in": 3600, "expiration": 1493747503 "scope": "ibm openid" }Sie finden das IAM-Token IBM Cloud im
access_tokenFeld Ihrer API-Ausgabe. Notieren Sie sich das IBM Cloud-IAM-Token, um weitere Headerinformationen in den nächsten Schritten abzurufen. -
Rufen Sie die ID des IBM Cloud-Kontos ab, mit dem Sie arbeiten wollen. Ersetzen Sie durch
TOKENdas IAM-Token IBM Cloud, das Sie im vorherigen Schritt aus dem Feldaccess_tokenIhrer API-Ausgabe abgerufen haben. In der API-Ausgabe finden Sie die ID Ihres IBM Cloud-Kontos im Feld resources.metadata.guid.GET https://accounts.cloud.ibm.com/coe/v2/accounts- Überschrift
-
Content-Type: application/jsonAuthorization: bearer TOKENAccept: application/json
Das folgende Beispiel zeigt die Ausgabe der vorherigen Anforderung.
{ "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>", -
Generieren Sie ein neues IBM Cloud-IAM-Token, das Ihre IBM Cloud-Berechtigungsnachweise und die Konto-ID enthält, mit der Sie arbeiten wollen.
Wenn Sie einen IBM Cloud-API-Schlüssel verwenden, müssen Sie die IBM Cloud-Konto-ID verwenden, für die der API-Schlüssel erstellt wurde. Um auf Cluster in anderen Konten zuzugreifen, melden Sie sich bei diesem Konto an und erstellen Sie einen API-Schlüssel für IBM Cloud, der auf diesem Konto basiert.
POST https://iam.cloud.ibm.com/identity/token- Überschrift
-
Content-Type: application/x-www-form-urlencodedAuthorization: Basic Yng6Yng=Dabei entsprichtYng6Yng=der als URL codierten Berechtigung für den Benutzernamen bx und das Kennwort bx.
- Hauptteil für IBM Cloud-Benutzername und -Kennwort
-
grant_type: passwordusername: Ihr IBM Cloud-Benutzername.password: Ihr IBM Cloud-Kennwort.bss_account: Die IBM Cloud-Konto-ID, die Sie im vorherigen Schritt abgerufen haben.
- Hauptteil für IBM Cloud-API-Schlüssel
-
grant_type: urn:ibm:params:oauth:grant-type:apikeyapikey: Ihr IBM Cloud-API-Schlüssel.bss_account: Die IBM Cloud-Konto-ID, die Sie im vorherigen Schritt abgerufen haben.
- Hauptteil für einmaligen IBM Cloud-Kenncode
-
grant_type: urn:ibm:params:oauth:grant-type:passcodepasscode: Ihr IBM Cloud-Kenncode.bss_account: Die IBM Cloud-Konto-ID, die Sie im vorherigen Schritt abgerufen haben.
Das folgende Beispiel zeigt die Ausgabe für die API-Anforderung.
{ "access_token": "<iam_token>", "refresh_token": "<iam_refresh_token>", "token_type": "Bearer", "expires_in": 3600, "expiration": 1493747503 }Sie finden das IAM-Token IBM Cloud im Feld und
access_tokendas Refresh-Token imrefresh_tokenFeld Ihrer API-Ausgabe. -
Listen Sie alle klassischen Cluster oder VPC-Cluster in Ihrem Konto auf. Wenn Sie Kubernetes-API-Anforderungen für Ihren Cluster ausführen, achten Sie darauf, den Namen oder die ID des Clusters zu notieren, mit dem Sie arbeiten möchten. Beispielanforderung zum Auflisten von Classic-Clustern.
GET https://containers.cloud.ibm.com/global/v2/classic/getClusters- Überschrift
Authorization: bearer <iam_token>
Beispielbefehl zum Auflisten von VPC-Clustern.
GET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2- Überschrift
Authorization: Ihr IBM Cloud IAM-Zugriffstoken (bearer <iam_token>).
-
In der API-Dokumentation von IBM Cloud Kubernetes Service finden Sie eine Liste der unterstützten APIs.
Wenn Sie die API für die Automatisierung verwenden, sollten Antworten der API berücksichtigt werden und nicht Dateien in diesen Antworten. Beispiel: Die Kubernetes-Konfigurationsdatei für Ihren Clusterkontext kann geändert werden. Erstellen
Sie daher keine Automatisierung auf der Basis bestimmter Inhalte dieser Datei, wenn Sie den Aufruf GET /v1/clusters/{idOrName}/config verwenden.
Mit dem Cluster unter Verwendung der Kubernetes-API arbeiten
Sie können die Kubernetes-API verwenden, um mit Ihrem Cluster in IBM Cloud Kubernetes Service zu interagieren.
Für die folgenden Anweisungen ist ein öffentlicher Netzzugriff in Ihrem Cluster erforderlich, um eine Verbindung zum Public-Cloud-Serviceendpunkt Ihres Kubernetes-Masters herzustellen.
-
Befolgen Sie die Schritte unter Cluster-Bereitstellungen mit der API automatisieren, um Ihren IAM-Zugriffstoken für IBM Cloud, Ihren API-Schlüssel für IBM Cloud, die ID des Clusters, in dem Sie Kubernetes-API-Anfragen ausführen möchten, sowie die Region IBM Cloud Kubernetes Service, in der sich Ihr Cluster befindet, abzurufen.
-
Abrufen einer IBM Cloud IAM-ID, eines IAM-Zugriffs und eines IAM-Aktualisierungs-Tokens unter Verwendung des IBM Cloud API-Schlüssels. In Ihrer API-Ausgabe finden Sie das IAM-ID-Token im Feld
id_token, das IAM-Zugriffstoken imaccess_tokenFeld und das IAM-Aktualisierungstoken imrefresh_tokenFeld.POST https://iam.cloud.ibm.com/identity/token- Überschrift
-
Content-Type: application/x-www-form-urlencodedAuthorization: Basic a3ViZTprdWJla3ViZTprdWJlentspricht der mit URL kodierten Autorisierung für den Benutzernamen undkubedas Passwortkube.
- Body
-
grant_type: urn:ibm:params:oauth:grant-type:apikeyapikey:Ihr IBM Cloud-API-Schlüssel.
Das folgende Beispiel zeigt die Ausgabe für die vorherige Anforderung.
{ "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" }Alternativ kann der CLI-Befehl
ibmcloud ks cluster config --cluster <cluster_name> --output jsonverwendet werden, um dieid_tokenund dierefresh_tokenanzuzeigen. -
Bevor Sie mit Ihrer aktuellen Identität auf Ihren Cluster zugreifen können, müssen Sie die folgende Anfrage ausführen.
POST https://containers.cloud.ibm.com/global/v2/applyRBAC- Überschrift
Authorization: bearer <TOKEN>Ihr IAM-Zugriffstoken für IBM Cloud- Body
cluster: <cluster_name_or_ID>
-
Beachten Sie, dass die RBAC-Synchronisierung asynchron ist. Führen Sie also die folgende Anforderung aus, bis die Synchronisierung abgeschlossen ist.
GET https://containers.cloud.ibm.com/global/v2/getRBACStatus?cluster=<cluster_name_or_ID>
-H "Autorisierung: ${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}
```
-
Rufen Sie die URL des Standardserviceendpunkts für Ihren Kubernetes-Master ab, indem Sie das IAM-Zugriffstoken und den Namen oder die ID Ihres Clusters verwenden. Sie finden die URL in der
masterURLIhrer API-Ausgabe.Wenn nur der Public-Cloud-Serviceendpunkt oder nur der Private-Cloud-Serviceendpunkt für Ihren Cluster aktiviert ist, wird dieser Endpunkt für die
masterURLaufgelistet. Wenn sowohl der Public- als auch der Private-Cloud-Serviceendpunkt für Ihren Cluster aktiviert ist, wird standardmäßig der Public-Cloud-Serviceendpunkt für diemasterURLaufgelistet. Um stattdessen den Private-Cloud-Serviceendpunkt zu verwenden, suchen Sie die URL im FeldprivateServiceEndpointURLin der Ausgabe.GET https://containers.cloud.ibm.com/global/v2/getCluster?cluster=<cluster_name_or_ID>- Überschrift
-
Authorization: Ihr IBM Cloud IAM-Zugriffstoken.
- Pfad
-
<cluster_name_or_ID>: Der Name bzw. die ID Ihres Clusters, den Sie mit der APIGET https://containers.cloud.ibm.com/global/v2/classic/getClustersoderGET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2in Clusterbereitstellungen mit der API automatisieren abgerufen haben.
Das folgende Beispiel zeigt die Ausgabe für eine öffentliche Cloud-Service-Endpunktanforderung.
... "etcdPort": "31593", "masterURL": "https://c2.us-south.containers.cloud.ibm.com:30422", "ingress": { ...}Das folgende Beispiel zeigt die Ausgabe für eine private Cloud-Service-Endpunktanforderung.
... "etcdPort": "31593", "masterURL": "https://c2.private.us-south.containers.cloud.ibm.com:30422", "ingress": { ...} -
Wenn Sie den Serviceendpunkt einer privaten Cloud verwenden möchten, müssen Sie zuerst den Serviceendpunkt der privaten Cloud über die IP-Adresse einer Lastausgleichsfunktion zugänglich machen, die von Ihrer VPN-Verbindung an das private Netz weitergeleitet werden kann.
-
Führen Sie die Kubernetes-API-Anforderungen für Ihren Cluster aus, indem Sie das IAM-ID-Token verwenden, das Sie zuvor abgerufen haben. Listen Sie zum Beispiel die Version von Kubernetes auf, die in Ihrem Cluster ausgeführt wird.
Wenn Sie die SSL-Zertifikatsprüfung in Ihrem API-Testframework aktiviert haben, müssen Sie diese Funktion inaktivieren.
GET <masterURL>/api- Überschrift
-
Authorization: bearer <id_token>
- Pfad
-
<masterURL>: Der Serviceendpunkt Ihres Kubernetes-Masters, den Sie im vorherigen Schritt abgerufen haben.
Das folgende Beispiel zeigt die Ausgabe für die vorherige API-Anforderung.
{ "kind": "APIVersions", "versions": [ "v1" ], "serverAddressByClientCIDRs": [ { "clientCIDR": "0.0.0.0/0", "serverAddress": "xxx.xx.x.x:xxxx" } ] } -
In der API-Dokumentation zu Kubernetes finden Sie eine Liste der unterstützten APIs für die neueste Version von Kubernetes. Achten Sie darauf, die API-Dokumentation zu verwenden, die mit der Kubernetes-Version Ihres Clusters übereinstimmt. Wenn Sie nicht die neueste Kubernetes-Version verwenden, fügen Sie Ihre Version am Ende der URL an. Fügen Sie z. B.
v1.12hinzu, um auf die API-Dokumentation für Version 1.12 zuzugreifen.
Aktualisieren von IAM-Zugriffstoken über die API
Jedes IBM Cloud Identity and Access Management-Zugriffstoken (IAM-Zugriffstoken), das über die API ausgegeben wird, läuft nach einer Stunde ab. Sie müssen Ihr Zugriffstoken regelmäßig aktualisieren, um den Zugriff auf die IBM Cloud-API sicherzustellen.
Bevor Sie beginnen, vergewissern Sie sich, dass Sie einen IBM Cloud API-Schlüssel haben, mit dem Sie ein neues Zugriffstoken anfordern können.
Führen Sie die folgenden Schritte aus, wenn Sie ein neues IBM Cloud IAM-Token erhalten möchten.
-
Erzeugen Sie ein neues IBM Cloud IAM-Zugriffstoken unter Verwendung des IBM Cloud API-Schlüssels.
POST https://iam.cloud.ibm.com/identity/token- Überschrift
-
Content-Type: application/x-www-form-urlencoded
- Body
-
grant_type: urn:ibm:params:oauth:grant-type:apikeyapikey:Ihr IBM Cloud-API-Schlüssel.
Das folgende Beispiel zeigt die Ausgabe für die vorherige API-Anforderung.
{ "access_token": "<iam_token>", "refresh_token": "<iam_refresh_token>", "token_type": "Bearer", "expires_in": 3600, "expiration": 1493747503, "scope": "ibm openid" }Sie finden Ihr neues IAM-Token für IBM Cloud im
access_tokenFeld Ihrer API-Ausgabe. -
Setzen Sie die Arbeit mit der API-Dokumentation zu IBM Cloud Kubernetes Service fort, indem Sie das Token aus dem vorherigen Schritt verwenden.