API einrichten

Red Hat® OpenShift® on IBM Cloud® nutzt dieselbe Anwendungsprogrammierschnittstelle (Application Programming Interface, API) wie IBM Cloud Kubernetes Service, sodass Sie Ihre Community-Kubernetes- oder Red Hat OpenShift-Cluster mit denselben Methoden konsistent erstellen und verwalten können. Informationen zur Verwendung der Befehlszeilenschnittstelle (CLI) finden Sie unter Befehlszeilenschnittstelle einrichten.

Informationen zur API

Die Red Hat OpenShift on IBM Cloud-API automatisiert die Bereitstellung und Verwaltung von IBM Cloud-Infrastrukturressourcen für Ihre Cluster, sodass Ihren Apps die nötigen Rechen-, Netz- und Speicherressourcen zur Verfügung stehen, um Ihren Benutzern dienlich sein zu können.

Die API unterstützt die verschiedenen Infrastrukturanbieter, die Ihnen für die Erstellung 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, PATCHund DELETE interagieren.
v2-API: RPCs (Remote Procedure Calls) mit Schwerpunkt auf Aktionen, die ausschließlich über GET- und POST-HTTP-Methoden erfolgen.
Unterstützte Containerplattformen
v1-API: Verwenden Sie die Red Hat OpenShift on IBM Cloud-API, um Ihre IBM Cloud-Infrastrukturressourcen, wie z. B. Workerknoten, sowohl für Kubernetes-Community als auch Red Hat OpenShift-Cluster zu verwalten.
v2-API: Verwenden Sie die Red Hat OpenShift on IBM Cloud v2-API, um Ihre IBM Cloud-Infrastrukturressourcen, wie z. B. Workerknoten, sowohl für Kubernetes-Community als auch Red Hat OpenShift-VPC-Cluster zu verwalten.
Red Hat OpenShift-API
v1 API: Um die Red Hat OpenShift API zur Verwaltung von Red Hat OpenShift und Kubernetes Ressourcen innerhalb des Clusters, wie Pods oder Namespaces, zu verwenden, müssen Sie sich anmelden, indem Sie einen IBM Cloud API-Schlüssel gegen ein Red Hat OpenShift Zugriffstoken austauschen. Weitere Informationen finden Sie unter API-Schlüssel für die Anmeldung bei Clustern verwenden.
v2-API: Identisch mit v1; siehe API-Schlüssel für die Anmeldung bei Clustern verwenden.
Unterstützte APIs nach Infrastrukturtyp
v1-API: classic
v2-API: vpc und classic
  • Der Provider vpc ist für die Unterstützung mehrerer VPC-Provider konzipiert. Der unterstützte Subprovider ist vpc-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 Beispiel GET vlan für die klassische Infrastruktur oder GET vpcs fü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.
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 eine GET-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 einer GET-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 Liste GET zones gibt zum Beispiel einige Ergebnisse wie mon01 zurück, die nur beim Provider der klassischen Infrastruktur verfügbar sind, während andere Ergebnisse wie us-south-01 nur 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 Red Hat OpenShift on IBM Cloud-API können Sie die Erstellung, Bereitstellung und Verwaltung Ihrer Red Hat OpenShift-Cluster automatisieren.

Die Red Hat OpenShift on IBM Cloud-API benötigt Headerinformationen, die Sie in Ihrer API-Anforderung angeben müssen. Diese Headerinformationen können je nach verwendeter API variieren. Um festzustellen, welche Header-Informationen für Ihre API benötigt werden, lesen Sie die Red Hat OpenShift on IBM Cloud API-Dokumentation.

Für die Authentifizierung bei Red Hat OpenShift on IBM Cloud müssen Sie ein IBM Cloud-IAM-Token (IAM = Identity and Access Management) angeben, dass mit Ihren IBM Cloud-Berechtigungsnachweisen erstellt wird und die IBM Cloud-Konto-ID enthält, mit 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
  • Erzeugen Sie einen IBM Cloud API-Schlüssel: Alternativ zur Verwendung des IBM Cloud Benutzernamens und Passworts können Sie IBM Cloud API-Schlüssel verwenden. IBM Cloud API-Schlüssel sind abhängig von dem IBM Cloud Konto, für das sie generiert werden. 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.
    1. Klicken Sie in der Menüleiste auf Verwalten > Zugriff (IAM).
    2. Klicken Sie auf die Seite Benutzer und wählen Sie Ihren eigenen Eintrag aus.
    3. Klicken Sie im Fenster API-Schlüssel auf IBM Cloud-API-Schlüssel erstellen.
    4. Geben Sie einen Namen und eine Beschreibung für Ihren API-Schlüssel ein und klicken Sie auf Erstellen.
    5. Klicken Sie auf Anzeigen, um den API-Schlüssel anzuzeigen, der für Sie generiert wurde.
    6. Kopieren Sie den API-Schlüssel, sodass Sie ihn zum Abrufen Ihres neuen IBM Cloud-IAM-Zugriffstokens verwenden können.

  1. 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-urlencoded
    • Authorization: Basic Yng6Yng= Dabei entspricht Yng6Yng= der als URL codierten Berechtigung für den Benutzernamen bx und das Kennwort bx.
    Hauptteil für IBM Cloud-Benutzername und -Kennwort
    • grant_type: password
    • username: 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:apikey
    • apikey: Ihr IBM Cloud-API-Schlüssel
    Hauptteil für einmaligen IBM Cloud-Kenncode
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • passcode: Ihr einmaliger IBM Cloud-Kenncode. Führen Sie den Befehl ibmcloud login --sso aus 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 IBM Cloud IAM-Token im Feld access_token Ihrer API-Ausgabe. Notieren Sie sich das IBM Cloud-IAM-Token, um weitere Headerinformationen in den nächsten Schritten abzurufen.

  2. Rufen Sie die ID des IBM Cloud-Kontos ab, mit dem Sie arbeiten wollen. Ersetzen Sie TOKEN durch das IAM-Token IBM Cloud, das Sie im vorherigen Schritt aus dem Feld access_token Ihrer 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/json
    • Authorization: bearer TOKEN
    • Accept: 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>",

  3. 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 IBM Cloud API-Schlüssel, der auf diesem Konto basiert.

    POST https://iam.cloud.ibm.com/identity/token
    Überschrift
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic Yng6Yng= Dabei entspricht Yng6Yng= der als URL codierten Berechtigung für den Benutzernamen bx und das Kennwort bx.
    Hauptteil für IBM Cloud-Benutzername und -Kennwort
    • grant_type: password
    • username: 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:apikey
    • apikey: 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:passcode
    • passcode: 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 IBM Cloud IAM-Token im access_token und das Refresh-Token im refresh_token Feld Ihrer API-Ausgabe.

  4. Listen Sie alle klassischen Cluster oder VPC-Cluster in Ihrem Konto auf. 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>).

  5. In der API-Dokumentation von Red Hat OpenShift on IBM Cloud 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.

Aktualisieren von IAM-Zugriffstokens mit der 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.

  1. Generieren 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:apikey
    • apikey: 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 IBM Cloud IAM-Token im Feld access_token Ihrer API-Ausgabe.

  2. Setzen Sie die Arbeit mit der Red Hat OpenShift on IBM Cloud API-Dokumentation fort, indem Sie das Token aus dem vorherigen Schritt verwenden.