使用服务绑定将 IBM Cloud 服务与 Code Engine

了解如何使用服务绑定将 IBM Cloud 服务实例集成到 IBM Cloud® Code Engine 项目中的资源。

服务绑定提供对 IBM Cloud 服务的应用程序，作业和功能访问权。

如果要使用 CLI 来处理服务绑定，并且您具有使用 **** CLI 1.27.0之前的 CLI 版本创建的服务绑定，请参阅注意事项以获取有关替换使用先前实现的服务绑定的信息。要充分利用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 Identity and Access Management (IAM) 启用的任何类型的 IBM Cloud 服务添加到应用程序，作业或功能工作负载中。要查找受支持 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 策略提供给具有服务标识的 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` 环境变量

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) 的公共环境变量语法向环境单独提供该变量。

缺省情况下，变量名称是服务的名称，后跟凭证变量的名称。例如，名为 apikey 的 IBM Cloud Object Storage 服务凭证变量在名为 CLOUD_OBJECT_STORAGE_APIKEY 的环境变量中可用。以下示例显示了为 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 服务有什么约束？

从 Code Engine 工作负载访问绑定的服务实例

CE_SERVICES 环境变量

前缀方法

如果我有使用先前实现的服务绑定，该考虑什么?

如何替换使用先前实现的服务绑定?

后续步骤

`CE_SERVICES` 环境变量