Arbeiten mit Servicebindungen für die Integration von IBM Cloud-Services in Code Engine

In diesem Abschnitt erfahren Sie, wie Sie eine IBM Cloud-Serviceinstanz für Ressourcen in einem IBM Cloud® Code Engine-Projekt mithilfe einer Servicebindung integrieren.

Servicebindungen ermöglichen den Zugriff auf Anwendungen, Jobs und Funktionen auf IBM Cloud-Services.

Wenn Sie die CLI zur Arbeit mit Service-Bindings verwenden und über Service-Bindings verfügen, die mit einer CLI-Version vor der Version „ 1.27.0 “ erstellt wurden, lesen Sie bitte den Abschnitt „Zu beachtende Punkte“, um Informationen zum Ersetzen von Service-Bindings zu erhalten, die die vorherige Implementierung verwenden. Um die neuesten Verbesserungen der CLI nutzen zu können, führen Sie ein Update auf die neueste Version der CLI unter IBM Cloud Code Engine durch.

Was ist eine IBM Cloud Code Engine-Servicebindung?

Durch das Binden einer Dienstinstanz an eine „ Code Engine “-Anwendung oder einen Job werden die Anmeldedaten für diese Dienstinstanz automatisch zu den Umgebungsvariablen des Containers für Ihre Anwendung oder den Job bzw. des Codebundles Ihrer Funktion hinzugefügt. Wenn Sie den Inhalt eines Serviceberechtigungsnachweises anzeigen möchten, rufen Sie das Dashboard für die Serviceinstanz auf und suchen Sie die Seite Serviceberechtigungsnachweise. Serviceberechtigungsnachweise werden als JSON-Objekte angezeigt, die bei einer Bindung zur Anwendung oder Jobumgebung hinzugefügt werden.

{
    "apikey": "xxxxxxx",
    "endpoints": "https://control.cloud-object-storage.cloud.ibm.com/v2/endpoints",
    "iam_apikey_description": "Auto-generated for key abcdabcd-abcd-4d8c-78cf-abcdabcdabcd",
    "iam_apikey_name": "my-object-storage-codeengine-credential",
    "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
    "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/1176a104ad4241e6b0aa82ed0b60c15c::serviceid:ServiceId-abcdabcd-7ae8-abcd-a219-abcdabcdabcd",
    "resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/1176a104ac4241e6b0cb82ed0b60c15c:abcdabcd-abcd-4777-abcd-d330a450c85b::"
}

Um eine Service-Instanz an Ihre „ Code Engine “-Workload zu binden, müssen Sie zunächst eine Instanz des Dienstes bereitstellen. Verwenden Sie anschließend die Konsole von Code Engine oder die Befehlszeilenschnittstelle, um Ihre App, Ihren Job oder Ihre Funktion an Ihre IBM Cloud-Serviceinstanz zu binden.

Wenn Sie eine Serviceinstanz an eine Code Engine-Workload binden, verwendet Code Engine einen geheimen Schlüssel für Servicezugriff, um den Berechtigungsnachweis der angegebenen IBM Cloud-Serviceinstanz zu speichern. Dieser Typ von geheimem Schlüssel ist der Schlüsselmechanismus in einer Servicebindung, der die Serviceinstanz von IBM Cloud mit einer bestimmten App, einem Job oder einer Funktion von Code Engine verbindet. Code Engine erstellt und verwaltet diesen geheimen Schlüssel für Sie.

Welche Servicetypen kann ich binden?
Sie können einen beliebigen Typ von IBM Cloud-Service hinzufügen, der für IBM Cloud Identity and Access Management (IAM) aktiviert ist und Serviceberechtigungsnachweise für Ihre Anwendungs-, Job-oder Funktionsworkload verwendet. Eine Liste der unterstützten IBM Cloud-Services finden Sie im IBM Cloud-Katalog.
Ich habe bereits Serviceberechtigungsnachweise für eine IBM Cloud-Serviceinstanz. Kann ich diese Berechtigungsnachweise mit Code Engine-Servicebindungen verwenden?
Ja, Sie können eine Service-Instanz mithilfe vorhandener Service-Anmeldedaten an „ Code Engine “-Workloads binden. Über die Konsole können Sie vorhandene Berechtigungsnachweise verwenden, die bereits in einer Servicebindung verwendet wurden. Wenn Sie vorhandene Serviceberechtigungsnachweise über die Befehlszeilenschnittstelle verwenden möchten, geben Sie die Option --service-credential in der ibmcloud ce application bind, ibmcloud ce job bind oder im Befehl ibmcloud ce function bind an und geben Sie den Namen Ihrer Serviceberechtigungsnachweise ein.
Welcher Zugriff ist zum Erstellen von Servicebindungen erforderlich?
Jedes „ Code Engine “-Projekt muss mit einer Reihe von IAM-Zugriffsrichtlinien konfiguriert werden, die den „ Code Engine “-Dienstbindungen die Berechtigung erteilen, Dienstinstanzen anzuzeigen sowie Dienstzugangsdaten in Ihrem Konto einzusehen und zu erstellen. IAM-Richtlinien werden für die Code Engine-Servicebindung mit einer Service-ID bereitgestellt. Weitere Informationen finden Sie unter Zugriff für Servicebindungen konfigurieren.
Gibt es eine Möglichkeit, Servicebindungsoperationen für alle Benutzer in einem Projekt zu konfigurieren?
Ja! Mit ausreichenden Berechtigungen können Sie die Seite 'Integration' in der Konsole verwenden, um Servicebindungsoperationen von einer einzelnen Seite aus zu konfigurieren. Wenn Sie nicht über ausreichende Berechtigungen zum Ausführen dieser Aktionen verfügen, können Sie diese Seite verwenden, um die erforderlichen Berechtigungen zu verstehen. Siehe Projektweite Einstellungen konfigurieren.
Wie ist nach dem Binden der Code Engine-Workload an eine Serviceinstanz die Lebensdauer dieser Servicebindung?
Wenn Sie eine Bindung zwischen Ihrer Code Engine-Workload und einer Serviceinstanz erstellen, ist die Servicebindung aktiv, solange die Code Engine-Workload und die Serviceinstanz aktiv sind oder Sie keine Operation zum Aufheben der Bindung ausgeführt haben, um die Servicebindung zu entfernen. Wenn die Serviceinstanz gelöscht wird, müssen Sie die Servicebindung manuell löschen. Wenn Sie die Bindung einer Servicebindung aufheben (oder entfernen), löschen Sie die Zuordnung der App, des Jobs oder der Funktion zum geheimen Schlüssel für Servicezugriff, sodass die App, der Job oder die Funktion keinen Zugriff mehr auf den zuvor gebundenen IBM Cloud-Service hat.

Zugriff auf eine gebundene Serviceinstanz über eine Code Engine-Workload

Code Engine stellt Umgebungsvariablen für den Zugriff auf Serviceinstanzen bereit, die mit den Methoden CE_SERVICES und PREFIX an Ihre Code Engine-Workload gebunden sind.

  • Die Umgebungsvariable CE_SERVICES ist eine einzelne Umgebungsvariable, die alle Servicebindungsinformationen als JSON-Objekt enthält.

  • Code Engine erstellt auch mehrere Umgebungsvariablen für Ihre Servicebindung, die auf den Variablen im Serviceberechtigungsnachweis für Ihre Serviceinstanz basieren. Um diese mehreren Umgebungsvariablen für Ihre Servicebindung zu unterscheiden, können Sie eine PREFIX verwenden, sodass diese Umgebungsvariablen dasselbe Präfix verwenden. Wenn Sie kein angepasstes Präfix angeben, generiert Code Engine automatisch ein Präfix.

Wenn Ihre Anwendung, Ihr Job oder Ihre Funktion über ein privates Netzwerk mit einem gebundenen Dienst kommunizieren soll und der Dienst sowohl Endpunkte vom Typ „ private “ als auch „ direct “ besitzt (z. B. IBM Cloud Object Storage ), müssen die Endpunkte vom Typ „ direct “ verwendet werden.

CE_SERVICES-Umgebungsvariable

Die Umgebungsvariable CE_SERVICES enthält Informationen, die Sie für die Interaktion mit einer Serviceinstanz verwenden können. Von dieser Umgebungsvariablen wird auf ein JSON-Objekt verwiesen, das Schlüssel/Wert-Paare enthält. Diese Schlüssel-Wert-Paare stehen für die einzelnen Diensttypen, die an Ihre Anwendung, Ihren Job oder Ihre Funktion gebunden sind. Hierbei steht key für den Namen des Servicetyps, zum Beispiel cloud-object-storage, und value steht für das Array der Berechtigungsnachweise für die gebundenen Serviceinstanzen für diesen Typ.

Das folgende Beispiel veranschaulicht eine Variable vom Typ „ CE_SERVICES “.

{
  "appid": [
    {
      "credentials": {
        "apikey": "xxxxxx",
        "appidServiceEndpoint": "https://us-south.appid.cloud.ibm.com",
        "clientId": "abcdabcd-xxxxxxxx",
        "discoveryEndpoint": "https://us-south.appid.cloud.ibm.com/oauth/v4/xxxxxxxx/.well-known/openid-configuration",
        "iam_apikey_description": "Auto-generated for key crn:v1:bluemix:public:appid:us-south:a/abcdabcd719f45b98a931f6e20db1bd8:xxxxxxxx:resource-key:abcdabcd-xxxxxxxx",
        "iam_apikey_name": "ce-service-access-abcd",
        "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
        "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/abcdabcd719f45b98a931f6e20db1bd8::serviceid:ServiceId-6d7087e5-0611-4240-9e46-af8a4c15cba4",
        "managementUrl": "https://us-south.appid.cloud.ibm.com/management/v4/xxxxxxxx",
        "oauthServerUrl": "https://us-south.appid.cloud.ibm.com/oauth/v4/xxxxxxxx",
        "profilesUrl": "https://us-south.appid.cloud.ibm.com",
        "secret": "abcdabcdYTAtZmU0MC00YTQ1LTliY2YtMDk0ODg0NDMyNDgw",
        "tenantId": "xxxxxxxx",
        "version": 4
      },
      "name": "App ID-yn",
      "plan": "c0258a22-160a-403b-845d-1588ad61204c",
      "resourcekey_name": "ce-service-access-abcd",
      "resourcekey_id": "abcdabcd-xxxxxxxx"
    }
  ],
  "cloud-object-storage": [
    {
      "credentials": {
        "apikey": "xxxxxx",
        "endpoints": "https://control.cloud-object-storage.cloud.ibm.com/v2/endpoints",
        "iam_apikey_description": "Auto-generated for key crn:v1:bluemix:public:cloud-object-storage:global:a/abcdabcd719f45b98a931f6e20db1bd8:abcdabcd-34b3-4edf-95b7-abcdabcdabcd:resource-key:abcdabcd-96e0-46ef-b805-31288524f194",
        "iam_apikey_name": "ce-service-access-c5yn1",
        "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
        "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/abcdabcd719f45b98a931f6e20db1bd8::serviceid:ServiceId-ee6394cb-f203-4c3c-9152-ac886a3f66bb",
        "resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/abcdabcd719f45b98a931f6e20db1bd8:abcdabcd-34b3-4edf-95b7-abcdabcdabcd::"
      },
      "name": "Cloud Object Storage-56",
      "plan": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "resourcekey_name": "ce-service-access-c5yn1",
      "resourcekey_id": "abcdabcd-96e0-46ef-b805-31288524f194"
    }
  ]
}

Präfixmethode

Bei Verwendung der Präfixmethode wird für jede einzelne Variable in einem Objekt für einen Serviceberechtigungsnachweis die Variable einzeln für die Umgebung angegeben; hierzu wird eine allgemeine Syntax für die Umgebungsvariable in Großbuchstaben verwendet, die durch Unterstriche getrennt sind, zum Beispiel VARIABLE_NAME.

Der Variablenname ist standardmäßig der Name des Service, gefolgt vom Namen der Variablen für den Berechtigungsnachweis. Beispielsweise ist eine Anmeldeinformationsvariable für den Dienst „ IBM Cloud Object Storage “ mit dem Namen „ apikey “ in einer Umgebungsvariablen namens „ CLOUD_OBJECT_STORAGE_APIKEY “ verfügbar. Im folgenden Beispiel werden die Umgebungsvariablen aufgeführt, die für die Bindung einer IBM Cloud Object Storage-Serviceinstanz erstellt werden.

CLOUD_OBJECT_STORAGE_APIKEY=xxxxxx
CLOUD_OBJECT_STORAGE_ENDPOINTS=https://control.cloud-object-storage.cloud.ibm.com/v2/endpoints
CLOUD_OBJECT_STORAGE_IAM_APIKEY_DESCRIPTION=Auto-generated for key abcdabcd-abcd-abcd-abcd-abcdabcdabcd
CLOUD_OBJECT_STORAGE_IAM_APIKEY_NAME=my-object-storage-codeengine-credential
CLOUD_OBJECT_STORAGE_IAM_ROLE_CRN=crn:v1:bluemix:public:iam::::serviceRole:Manager
CLOUD_OBJECT_STORAGE_IAM_SERVICEID_CRN=crn:v1:bluemix:public:iam-identity::a/1176a104ad4441e6b0aa92ed0b60b15c::serviceid:ServiceId-abcdabcd-abcd-abcd-8b41-531fc64e640e
CLOUD_OBJECT_STORAGE_RESOURCE_INSTANCE_ID=crn:v1:bluemix:public:cloud-object-storage:global:a/1176a104ad4441e6b0aa92ed0b60b15c:11179ac4-abcd-4887-abcd-d330a430abcd::
CLOUD_OBJECT_STORAGE_SERVICENAME=my-object-storage

Standardmäßig gilt: Wenn mehrere Instanzen desselben Typs an eine einzelne Anwendung gebunden werden, dann wird von Code Engine ein Index an den Servicenamen angehängt, beispielsweise CLOUD_OBJECT_STORAGE_2_APIKEY.

Jede Servicebindung kann für die Verwendung eines Präfix für angepasste Umgebungsvariablen konfiguriert werden. Wenn Sie die Konsole verwenden, können Sie bei der Erstellung der Servicebindung optional ein Präfix angeben. Wenn Sie die Befehlszeilenschnittstelle verwenden, verwenden Sie die Option --prefix im app bind, im job bind oder im Befehl function bind.

Was muss ich beachten, wenn ich über Servicebindungen verfüge, welche die vorherige Implementierung verwenden?

In CLI 1.27.0 wurde eine verbesserte Servicebindungsimplementierung eingeführt, die für alle Bindungen verwendet wird, die mit dieser Version oder höher erstellt werden. Servicebindungen, die mit einer Version der CLI vor CLI 1.27.0 erstellt wurden, verwenden die vorherige Servicebindungsimplementierung. Anwendungen, Jobs und Funktionen, deren Service-Bindungen auf der bisherigen Implementierung basieren, funktionieren hinsichtlich des Zugriffs auf die gebundenen Dienste weiterhin einwandfrei. Wenn Sie jedoch Servicebindungen ändern möchten, welche die vorherige Implementierung verwenden, beachten Sie die folgenden Informationen.

  • Für dieselbe App, denselben Job oder dieselbe Funktion dürfen keine Service-Bindungen aus einer früheren Implementierung und einer verbesserten Implementierung gemischt werden. Bevor Sie einer App, einem Job oder einer Funktion, deren Service-Bindungen die bisherige Implementierung verwenden, neue Service-Bindungen hinzufügen können, müssen Sie alle diese Service-Bindungen aufheben. Anschließend können Sie sie mit der verbesserten Implementierung erneut erstellen und neue Servicebindungen hinzufügen.
  • Sie können die Bindung dieser Servicebindungen nicht einzeln aufheben. Sie müssen alle entfernen, indem Sie den Befehl app unbind --all oder job unbind --all verwenden.
  • Wenn Sie mit Funktionsworkloads arbeiten, verwendet Ihre Funktion automatisch die neueste Implementierung von Servicebindungen.

Wenn Sie die neuesten Erweiterungen nutzen und die Servicebindungen für Ihre Apps und Jobs ohne großen Aufwand verwalten möchten, aktualisieren Sie auf die neueste IBM Cloud Code Engine-CLI-Version und ersetzen Sie die Servicebindungen, welche die vorherige Implementierung verwenden.

Wie kann ich eine Servicebindung ersetzen, die die vorherige Implementierung verwendet?

Wenn Ihre Anwendung oder Ihr Job Service-Bindungen enthält, die die bisherige Implementierung verwenden, und Sie Ihrer Anwendung oder Ihrem Job neue Service-Bindungen hinzufügen möchten, müssen Sie zunächst die Bindungen entfernen, die die bisherige Implementierung verwenden, bevor neue Bindungen erstellt werden. Sie können diese vorhandenen Servicebindungen bei Bedarf erneut erstellen.

Ihre Anwendung ist während der Aufhebung der Bindung und der erneuten Bindung möglicherweise nicht voll funktionsfähig.

  1. Um herauszufinden, ob Ihre Anwendung oder Ihr Job die bisherige Implementierung von Service-Bindings verwendet, führen Sie den Befehl app get oder job get Befehl aus. Wenn die bisherige Implementierung der Dienstbindung verwendet wird, enthält die Ausgabe dieses Befehls die Informationen sowie die Befehle, die Sie verwenden müssen, um einen anderen Dienst an die Anwendung oder den Job zu binden. Beispiel:

    ibmcloud ce app get --name myapp

    Beispielausgabe

    Run 'ibmcloud ce application events -n myapp' to get the system events of the application instances.
Run 'ibmcloud ce application logs -f -n myapp' to follow the logs of the application instances.
OK
This application uses a previous service binding implementation.
Your application will continue to function normally.
To bind an additional service to this application, delete and re-create those service bindings with the improved implementation.
Your application might not be fully functional during the process of unbinding and rebinding.
Re-create the existing service bindings by issuing the following commands:
(1) Remove all existing service bindings from this application.
ibmcloud ce application unbind --name myapp -all
(2) Bind the services again.
ibmcloud ce application bind --name myapp --service-instance myobjectstorage --prefix CLOUD_OBJECT_STORAGE
Name:               myapp
ID:                 abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:       myproject
Project ID:         01234567-abcd-abcd-abcd-abcdabcd1111
Age:                2m4s
Created:            2021-09-09T14:01:02-04:00
URL:                https://myapp.abcdabcdabc.us-south.codeengine.appdomain.cloud
Cluster Local URL:  http://myapp.abcdabcdabc.svc.cluster.local
Console URL:        https://cloud.ibm.com/codeengine/project/us-south/01234567-abcd-abcd-abcd-abcdabcd1111/application/myapp/configuration
Status Summary:     Application deployed successfully
[...]
Service Bindings:
Service Instance    Service Type           Environment Variable Prefix
myobjectstorage     cloud-object-storage   CLOUD_OBJECT_STORAGE

    Wenn Sie mit Jobs arbeiten, führen Sie den Befehl ibmcloud ce job get --name JOB_NAME aus, um herauszufinden, ob veraltete Bindungen in Ihrem Job verwendet werden.

  2. Heben Sie die Bindung der vorhandenen Servicebindungen auf, welche die vorherige Implementierung verwenden. Die Option --all gibt an, dass die Bindung aller Serviceinstanzen für diese Anwendung aufgehoben werden soll.

    ibmcloud ce app unbind --name APP_NAME --all

    Wenn Sie mit Jobs arbeiten, führen Sie den Befehl ibmcloud ce job unbind --name JOB_NAME --all aus, um die Bindung aller Serviceinstanzen für Ihren Job aufzuheben.

  3. Neue Bindungen erstellen. Führen Sie den Befehl ibmcloud ce app bind oder ibmcloud ce job bind aus, um neue Bindungen zu erstellen. Zum Ersetzen der Servicebindung, die die vorherige Implementierung verwendet hat, verwenden Sie die Befehle, die in der Ausgabe der Befehle app get oder job get bereitgestellt werden. Wenn Sie beispielsweise eine vorhandene Bindung von der Code Engine-Anwendung ( myapp) zur IBM Cloud Object Storage-Serviceinstanz myobjectstorage erneut erstellen möchten,

    ibmcloud ce app bind --name myapp --service-instance myobjectstorage --prefix CLOUD_OBJECT_STORAGE

    Wenn Sie mit Jobs arbeiten, führen Sie den Befehl ibmcloud ce job bind --name JOB_NAME ---service-instance SERVICE_INSTANCE --prefix PREFIX aus.

    Wiederholen Sie diesen Schritt für jede Bindung, die erneut erstellt werden soll.

  4. (optional) Führen Sie den Befehl app get oder job get erneut aus. Beachten Sie dieses Mal, dass die Ausgabe des Befehls keine Informationen zu Servicebindungen mit einer früheren Implementierung anzeigt. Beispiel:

    ibmcloud ce app get --name myapp

    Beispielausgabe

    Run 'ibmcloud ce application events -n myapp' to get the system events of the application instances.
Run 'ibmcloud ce application logs -f -n myapp' to follow the logs of the application instances.
OK
Name:               myapp
ID:                 abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:       myproject
Project ID:         01234567-abcd-abcd-abcd-abcdabcd1111
Age:                2m4s
Created:            2021-09-09T14:01:02-04:00
URL:                https://myapp.abcdabcdabc.us-south.codeengine.appdomain.cloud
Cluster Local URL:  http://myapp.abcdabcdabc.svc.cluster.local
Console URL:        https://cloud.ibm.com/codeengine/project/us-south/01234567-abcd-abcd-abcd-abcdabcd1111/application/myapp/configuration
Status Summary:     Application deployed successfully
[...]
Service Bindings:
Name                                         ID                                    Service Instance      Service Type          Role / Credential  Environment Variable Prefix
myapp-app-ce-service-binding-abcde          abcde5d3-dfc3-4f52-b133-b869b5eabcde   my-object-storage    cloud-object-storage   Writer             CLOUD_OBJECT_STORAGE

Nächste Schritte

Bevor Sie eine Serviceinstanz an eine Code Engine-App, Job oder Funktionsworkload binden können, müssen Sie den Zugriff für Bindungen konfigurieren. Siehe Zugriff für Servicebindungen konfigurieren.