使用服務連結來整合 IBM Cloud 服務與 Code Engine

瞭解如何透過服務綁定，將 IBM Cloud 服務實例整合至 IBM Cloud® Code Engine 專案中的資源。

服務連結可讓應用程式、工作及功能存取 IBM Cloud 服務。

如果您正在使用 CLI 處理服務綁定，且擁有使用 CLI 1.27.0之前版本所建立的服務綁定，請參閱「注意事項」以了解如何替換使用舊版實作的服務綁定。若要善用 CLI 的最新增強功能，請更新至最新版本的 IBM Cloud Code Engine CLI。

什麼是 IBM Cloud Code Engine 服務綁定？

將服務實例連結至 Code Engine 應用程式或工作會自動將服務實例的認證新增至應用程式或工作之容器的環境變數，或新增至函數的程式碼組合。若要查看服務認證的內容，請跳至服務實例的儀表板，並找到 服務認證 頁面。服務認證會顯示為 JSON 物件，當連結時，會新增至應用程式或工作環境。

{
    "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::"
}

若要將服務實例綁定至您的 Code Engine 工作負載，您必須先為該服務配置一個實例。然後，使用 Code Engine 主控台或 CLI 將應用程式、工作或函數連結至 IBM Cloud 服務實例。

當您將服務實例連結至 Code Engine 工作量時，Code Engine 會使用 服務存取密碼 來儲存所指定 IBM Cloud 服務實例的認證。此類型的密碼是服務連結中的金鑰機制，它會將 IBM Cloud 服務實例連接至特定 Code Engine 應用程式、工作或函數。Code Engine 會為您建立並管理此密鑰。

我可以連結哪些類型的服務?: 您可以新增任何類型的 IBM Cloud 服務 (針對 IBM Cloud Identity and Access Management (IAM) 啟用)，並將服務認證用於應用程式、工作或函數工作量。若要尋找支援的 IBM Cloud 服務清單，請參閱 IBM Cloud 型錄。
我已有 IBM Cloud 服務實例的服務認證。我可以搭配使用這些認證與 Code Engine 服務連結嗎?: 是，您可以使用現有服務認證，將服務實例連結至 Code Engine 工作量。從主控台，您可以使用已在服務連結中使用的現有認證。若要從 CLI 使用現有服務認證，請在 ibmcloud ce application bind、ibmcloud ce job bind 或 ibmcloud ce function bind 指令中指定 --service-credential 選項，並提供服務認證的名稱。
需要哪些存取權才能建立服務連結?: 每一個 Code Engine 專案都必須配置一組 IAM 存取原則，這會授權 Code Engine 服務連結檢視服務實例，以及檢視和建立您帳戶中的服務認證。 IAM 原則提供給具有服務 ID 的 Code Engine 服務連結。如需相關資訊，請參閱配置服務連結的存取權。
是否有方法為專案中的所有使用者配置服務連結作業?: 是的！如果有足夠的許可權，您可以使用主控台中的「整合」頁面，從單一頁面來配置服務連結作業。如果您沒有足夠許可權來執行這些動作，您可以利用這個頁面來協助您瞭解必要的許可權。請參閱配置專案層面的設定。
將我的 Code Engine 工作量連結至服務實例之後，此服務連結的生命期限為何?: 當您在 Code Engine 工作量與服務實例之間建立連結時，只要 Code Engine 工作量且服務實例處於作用中狀態，服務連結就會處於作用中狀態，或者您尚未完成取消連結作業來移除服務連結。如果刪除服務實例，您將需要手動刪除服務連結。當您取消連結 (或移除) 服務連結時，會刪除應用程式、工作或函數與服務存取密碼的關聯，以便應用程式、工作或函數不再具有先前所連結 IBM Cloud 服務的存取權。

從 Code Engine 工作量存取連結服務實例

Code Engine 提供環境變數，用於存取同時使用 CE_SERVICES 及 PREFIX 方法來連結至 Code Engine 工作量的服務實例。

CE_SERVICES 環境變數是單一環境變數，包含作為 JSON 物件的所有服務連結資訊。
Code Engine 也會為服務連結建立多個環境變數，這些環境變數基於服務實例的服務認證中的變數。若要區分服務連結的這些多個環境變數，您可以使用 PREFIX，以便這些環境變數使用相同的字首。如果您未指定自訂字首，Code Engine 會自動產生字首。

若您的應用程式、工作或函式希望透過私有網路與已綁定的服務進行通訊，且該服務同時具備 private 與 direct 兩個端點（例如 IBM Cloud Object Storage ），則必須使用 direct 端點。

`CE_SERVICES` 環境變數 (environment variable)

CE_SERVICES 環境變數包含可用於與服務實例進行互動的資訊。此環境變數指向包含鍵值組的 JSON 物件。這些鍵值組代表連結至應用程式、工作或功能的每一種服務類型。 key 是服務類型的名稱 (例如 cloud-object-storage)，而 value 是該類型所連結服務實例的認證陣列。

下列範例說明 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"
    }
  ]
}

字首方法

使用字首方法，針對服務認證物件中的每一個認證變數，會使用以底線區隔的大寫字母一般環境變數語法 (例如 VARIABLE_NAME)，將該變數個別提供給您的環境。

依預設，變數名稱是服務的名稱，後面接著認證變數的名稱。例如，名為 CLOUD_OBJECT_STORAGE_APIKEY 的環境變數中提供名為 apikey 的 IBM Cloud Object Storage 服務認證變數。下列範例顯示針對 IBM Cloud Object Storage 服務實例連結所建立的環境變數。

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

依預設，如果多個相同類型的實例連結至單一應用程式，則 Code Engine 會將索引附加至服務名稱，例如 CLOUD_OBJECT_STORAGE_2_APIKEY。

每一個服務連結都可以配置成使用自訂環境變數字首。如果您使用主控台，則可以在建立服務連結時選擇性地提供字首。如果您使用 CLI，請搭配使用 --prefix 選項與 app bind、job bind 或 function bind 指令。

如果我有使用先前實作的服務連結，我應該考慮什麼?

CLI 1.27.0 引進改良的服務連結實作，用於以這個版本或更新版本所建立的所有連結。在 CLI 1.27.0 之前的 CLI 版本所建立的服務連結會使用先前的服務連結實作。具有使用先前實作之服務連結的應用程式、工作及功能，會繼續正常運作，以存取連結的服務。不過，如果您想要變更使用先前實作的服務連結，請考量下列資訊。

對於相同的應用程式、工作或功能，您不能混合先前的實作及改良的實作服務連結。您必須先取消連結所有這些服務連結，才能將新的服務連結新增至具有使用先前實作之服務連結的應用程式、工作或函數。然後，您可以使用改良的實作來重建它們，並新增服務連結。
您無法個別取消連結這些服務連結。您必須使用 app unbind --all 或 job unbind --all 指令將它們全部移除。
如果您使用「函數」工作量，則您的函數會自動使用服務連結的最新實作。

若要善用最新的功能增強，並繼續輕鬆管理應用程式和工作的服務綁定，請更新至最新版本的 IBM Cloud Code Engine CLI，並替換那些使用舊版實作的服務綁定。

如何取代使用先前實作的服務連結?

如果您的應用程式或工作有使用先前實作的服務綁定，而您要新增新的服務綁定到應用程式或工作，您必須先移除使用先前實作的綁定，才能建立新的綁定。必要的話，您可以重建那些現有的服務連結。

在解除綁定與重新綁定的過程中，您的應用程式可能無法完全正常運作。

若要瞭解您的應用程式或工作是否使用先前的服務綁定實作，請執行 app get 或 job get 命令。如果使用先前的服務連結實作，這個指令的輸出會提供資訊，以及您必須用來將另一個服務連結至應用程式或工作的指令。例如，

ibmcloud ce app get --name myapp

輸出範例

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

同樣地，如果您使用工作，請執行 ibmcloud ce job get --name JOB_NAME 指令來探索是否將已淘汰的連結與工作搭配使用。

取消連結使用先前實作的現有服務連結。 --all 選項指定取消連結此應用程式的所有服務實例。
```
ibmcloud ce app unbind --name APP_NAME --all
```
同樣地，如果您使用工作，請執行 ibmcloud ce job unbind --name JOB_NAME --all 指令來取消連結工作的所有服務實例。
建立新的連結。如果要建立新的連結，請執行 ibmcloud ce app bind 或 ibmcloud ce job bind 指令。如果要取代使用先前實作的服務連結，請使用 app get 或 job get 指令輸出中提供的指令。例如，若要重建從 Code Engine 應用程式 myapp 至 IBM Cloud Object Storage 服務實例 myobjectstorage 的現有連結，請執行下列指令:
```
ibmcloud ce app bind --name myapp --service-instance myobjectstorage --prefix CLOUD_OBJECT_STORAGE
```
同樣地，如果您正在使用工作，請執行 ibmcloud ce job bind --name JOB_NAME ---service-instance SERVICE_INSTANCE --prefix PREFIX 指令。

請針對每個您想要重新建立的綁定，重複此步驟。

(選用) 重新執行 app get 或 job get 指令。這次請注意，指令的輸出不會顯示含有先前實作之服務連結的相關資訊。例如，

ibmcloud ce app get --name myapp

輸出範例

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

下一步

您必須先配置連結的存取權，然後才能將服務實例連結至 Code Engine 應用程式、工作或函數工作量。請參閱配置服務連結的存取權。

使用服務連結來整合 IBM Cloud 服務與 Code Engine

使用服務連結來整合 IBM Cloud 服務與 Code Engine

什麼是 IBM Cloud Code Engine 服務綁定？

從 Code Engine 工作量存取連結服務實例

CE_SERVICES 環境變數 (environment variable)

字首方法

如果我有使用先前實作的服務連結，我應該考慮什麼?

如何取代使用先前實作的服務連結?

下一步

`CE_SERVICES` 環境變數 (environment variable)