IBM Cloud Docs
Working with service bindings to integrate IBM Cloud services with Code Engine

Working with service bindings to integrate IBM Cloud services with Code Engine

Find out how to integrate an IBM Cloud service instance to resources in an IBM Cloud® Code Engine project by using service binding.

Service bindings provide applications, jobs, and functions access to IBM Cloud services.

If you are using the CLI to work with service bindings, and you have service bindings that were created with a version of the CLI before CLI 1.27.0, see considerations for information about replacing service bindings that use the previous implementation. To take advantage of the latest enhancements of the CLI, update to the latest IBM Cloud Code Engine CLI version.

What is IBM Cloud Code Engine service binding?

Binding a service instance to a Code Engine application or job automatically adds credentials for a service instance to the environment variables of the container for your application or the job, or the code bundle of your Function. To see the contents of a service credential, go to the dashboard for the service instance and locate the Service credentials page. Service credentials are shown as a JSON object, which, when bound, are added to the application or job environment.

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

To bind a service instance to your Code Engine workload, you must provision an instance of the service first. Then, use the Code Engine console or the CLI to bind your app, job, or function to your IBM Cloud service instance.

When you bind a service instance to a Code Engine workload, Code Engine uses a service access secret to store the credential of the specified IBM Cloud service instance. This type of secret is the key mechanism in a service binding that connects the IBM Cloud service instance to a particular Code Engine app, job, or function. Code Engine creates and manages this secret for you.

What types of services can I bind?
You can add any type of IBM Cloud service that is enabled for IBM Cloud Identity and Access Management (IAM) and that uses service credentials to your application, job, or function workload. To find a list of supported IBM Cloud services, see the IBM Cloud catalog.
I already have service credentials for an IBM Cloud service instance. Can I use these credentials with Code Engine service bindings?
Yes, you can bind a service instance to Code Engine workloads by using existing service credentials. From the console, you can use existing credentials that are already used in a service binding. To use existing service credentials from the CLI, specify the --service-credential option in the ibmcloud ce application bind, ibmcloud ce job bind, or the ibmcloud ce function bind command and provide the name of your service credentials.
What access is required to create service bindings?
Each Code Engine project must be configured with a set of IAM Access policies, which authorizes Code Engine service bindings to view service instances and to view and create service credentials in your account. IAM policies are provided to Code Engine service binding with a service ID. For more information, see Configuring access for service bindings.
Is there a way to configure service binding operations for all users in a project?
Yes! With sufficient permissions, you can use the Integration page in the console to configure service binding operations from a single page. If you don't have sufficient permissions to perform these actions, you can use this page to help you understand the required permissions. See Configuring project-wide settings.
After binding my Code Engine workload to a service instance, what's the life of this service binding?
When you create a binding between your Code Engine workload and a service instance, the service binding is active as long as the Code Engine workload and the service instance is active, or you haven't completed an unbind operation to remove the service binding. If the service instance is deleted, you'll need to manually delete the service binding. When you unbind (or remove) a service binding, you are deleting the association of the app, job, or function with the service access secret such that the app, job, or function no longer has access to previously bound IBM Cloud service.

Accessing a bound service instance from a Code Engine workload

Code Engine provides environment variables for accessing service instances that are bound to your Code Engine workload with both the CE_SERVICES and PREFIX methods.

  • The CE_SERVICES environment variable is a single environment variable that contains all service binding information as a JSON object.

  • Code Engine also creates multiple environment variables for your service binding, which are based on the variables in the service credential for your service instance. To distinguish these multiple environment variables for your service binding, you can use a PREFIX such that these environment variables use the same prefix. If you do not specify a custom prefix, Code Engine automatically generates a prefix.

If your application, job, or function wants to talk to a bound service by using private networking and the service has both private and direct endpoints (such as IBM Cloud Object Storage), then the direct endpoints must be used.

CE_SERVICES environment variable

The CE_SERVICES environment variable contains information that you can use to interact with a service instance. This environment variable points to a JSON object that contains key value pairs. These key value pairs represent each type of service that is bound to your application, job, or function. The key is the name of the service type, such as cloud-object-storage, and the value is an array of credentials for bound service instances of that type.

The following example illustrates a CE_SERVICES variable.

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

Prefix method

With the prefix method, for each credential variable in a service credential object, that variable is provided individually to your environment by using the common environment variable syntax of capital letters that are separated by underscores, such as VARIABLE_NAME.

By default, the variable name is the name of the service, followed by the name of credential variable. For example, an IBM Cloud Object Storage service credential variable that is named apikey is available in an environment variable that is called CLOUD_OBJECT_STORAGE_APIKEY. The following example shows the environment variables that are created for an IBM Cloud Object Storage service instance binding.

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

By default, if more than one instance of the same type is bound to a single application, Code Engine appends an index to the service name, such as CLOUD_OBJECT_STORAGE_2_APIKEY.

Each service binding can be configured to use a custom environment variable prefix. If you are using the console, you can optionally provide a prefix when you create the service binding. If you are using the CLI, use the --prefix option with the app bind, the job bind, or the function bind command.

What should I consider if I have service bindings that use the previous implementation?

CLI 1.27.0 introduced an improved service binding implementation, which is used for all bindings that are created with this version or later. Service bindings that were created with a version of the CLI before CLI 1.27.0 are using the previous service binding implementation. Applications, jobs, and functions that have service bindings that use the previous implementation continue to function normally regarding access to the bound services. However, if you want to change service bindings that use the previous implementation, consider the following information.

  • You cannot have a mixture of previous implementation and improved implementation service bindings for the same app, job, or function. Before you can add new service bindings to an app, job, or function that has service bindings that use the previous implementation, you must unbind all these service bindings. You can then re-create them with the improved implementation and add new service bindings.
  • You cannot individually unbind these service bindings. You must remove them all by using the app unbind --all or job unbind --all command.
  • If you are working with Function workloads, your function automatically uses the latest implementation of service bindings.

To take advantage of the latest enhancements and continue to manage service bindings for your apps and jobs easily, update to the latest IBM Cloud Code Engine CLI version and replace service bindings that use the previous implementation.

How can I replace a service binding that uses the previous implementation?

If your app or job has service bindings that use the previous implementation, and you want to add new service bindings to your app or job, you must first remove the bindings that use the previous implementation before new bindings are created. You can re-create those existing service bindings if needed.

Your application might not be fully functional during the process of unbinding and rebinding.

  1. To discover if your app or job uses the previous implementation of service bindings, run the app get or job get command. If the previous service binding implementation is used, the output of this command provides the information, and the commands that you must use to bind another service to the application or job. For example,

    ibmcloud ce app get --name myapp

    Example output

    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

    Similarly, if you are working with jobs, run the ibmcloud ce job get --name JOB_NAME command to discover if deprecated bindings are used with your job.

  2. Unbind the existing service bindings that use the previous implementation. The --all option specifies to unbind all service instances for this application.

    ibmcloud ce app unbind --name APP_NAME --all

    Similarly, if you are working with jobs, run the ibmcloud ce job unbind --name JOB_NAME --all command to unbind all service instances for your job.

  3. Create new bindings. To create new bindings, run the ibmcloud ce app bind or ibmcloud ce job bind command. To replace service binding that used the previous implementation, use the commands that are provided in the output of the app get or job get commands. For example, to re-create an existing binding from the Code Engine application, myapp, to the IBM Cloud Object Storage service instance, myobjectstorage,

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

    Similarly, if you are working with jobs, run the ibmcloud ce job bind --name JOB_NAME ---service-instance SERVICE_INSTANCE --prefix PREFIX command.

    Repeat this step for each binding that you want to re-create.

  4. (optional) Run the app get or job get command again. This time, notice that the output of the command does not display the information about service bindings with a previous implementation. For example,

    ibmcloud ce app get --name myapp

    Example output

    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

Next steps

Before you can bind a service instance to a Code Engine app, job, or function workload, you must configure access for bindings. See Configuring access for service bindings.