サービス・バインディングを使用した 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 アプリケーションまたはジョブにバインドすると、そのサービスインスタンスの認証情報が、アプリケーションまたはジョブのコンテナ、あるいはFunctionのコードバンドルの環境変数に自動的に追加されます。 サービス資格情報の内容を確認するには、サービス・インスタンスのダッシュボードに移動し、**「サービス資格情報」**ページを見つけます。 バインドしたときにアプリケーションまたはジョブの環境に追加されたサービス資格情報が、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 ポリシーは、サービス 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環境変数
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
デフォルトでは、同じタイプの複数のインスタンスを 1 つのアプリケーションにバインドすると、Code Engine が、CLOUD_OBJECT_STORAGE_2_APIKEY のように、サービス名にインデックスを追加します。
各サービス・バインディングは、カスタム環境変数接頭部を使用するように構成できます。 コンソールを使用している場合は、サービス・バインディングの作成時にオプションで接頭部を指定できます。 CLI を使用する場合は、 app bind、 job bind、または function bind コマンドで
--prefix オプションを使用します。
前の実装を使用するサービス・バインディングがある場合は、何を考慮する必要がありますか?
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 アプリ、ジョブ、または関数ワークロードにバインドする前に、バインディングのアクセス権限を構成する必要があります。 サービス・バインディングのアクセスの構成 を参照してください。