Binding a service instance to an app, job, or function workload

You can integrate an IBM Cloud service instance to resources in an IBM Cloud® Code Engine project by using service bindings.

After determining the service instance that you want to bind to your Code Engine workload, and ensuring that you have configured access for service bindings, you are ready to bind the service instance to your Code Engine app, job, or function workload.

Before you begin

Create a project.
Create a Code Engine workload to bind to your service instance. The workload that you want to bind to the service instance must exist.
Create the service instance that you want to bind to your Code Engine workload.
Configure access for service bindings.

Access for service bindings must be configured before you can bind a service instance to a Code Engine app, job, or function workload. Configure access for service bindings based on whether you want Code Engine to automatically create and manage the service ID for you or whether you want to use a service ID that you manage.

When you work with service bindings, what is the relationship between the service ID, service access secrets, and service credentials?: In Code Engine, a service binding is the relationship between an app, job, or function workload and another IBM Cloud service. Code Engine uses a service ID to create credentials for a specific IBM Cloud service instance. These credentials are service credentials and are used by your Code Engine project to interact with the service instance. Service credentials are stored in a service access secret. A service access secret can be accessed by an app, job, or function with the service credentials and is used to interact with the service instance.; When you create your IBM Cloud service instance, you can choose to create the service credential for that service instance. Or, when you create a service binding, you can choose for Code Engine to automatically create the service instance credential for you if you configured access for service bindings.; Whether you choose for Code Engine to automatically create the service credential for you or you manually create the service credential for a specific service instance, you must specify the Identity and Access Management (IAM) role for the service credential. The role that you specify defines the interaction that is allowed with the specific service instance and the bound Code Engine app, job, or function. For example, if you create a service binding from Code Engine to an IBM Cloudant service instance and you want the app, job, or function only to read from the IBM Cloudant database, select the Reader role.

Binding a service instance to a Code Engine app or job from the console

You can create a service binding that binds an existing service instance to a Code Engine app or job by using the console. To create a service binding for a function, you must use the CLI.

Binding a service instance with a new service access secret (with a Code Engine autogenerated credential)

Let's create a service binding to bind a service instance to an app or job with a new service access secret that uses a service credential that is automatically generated by Code Engine. For this example, create a service binding from the console for the myapp app and choose for Code Engine to automatically create the service credential to an IBM Cloud service instance. Before Code Engine can automatically create the service credential, ensure that you configure access for Code Engine to automatically create and manage the service ID for service bindings.

After your project is in Active status, click the name of your project on the Code Engine Projects page.
From the Overview page, click Service bindings.
From the Service bindings page, click Create to create the binding.
Select the IBM service instance that you want to bind to your Code Engine app or job.
Select the Code Engine app or job that you want to bind to the service instance; for example, choose the myapp app.
Specify the service access secret to use with this binding. The service access secret stores the credential for the service binding. Notice that any previously defined service credential for your specific service instance, which is not associated with the app or job that you selected, is listed. If no service access secret currently exists, then you are creating a new secret. If a service access secret does exist, to create a new service access secret with a new service credential for this binding, select New secret. Complete the following steps.
1. Select the Role for the service instance credential.
2. Expand Advanced options.
3. For Code Engine to automatically create the service credential to an IBM Cloud service instance, select Auto-generate.
4. (optional) Specify a custom prefix for the service binding. If you do not specify a custom prefix, Code Engine automatically generates a prefix. The prefix is used to distinguish environment variables that are created for this service binding.
Click Add to create the service binding.
Now that your service binding to your app or job is created from the console, you can view a list of all defined service bindings between service instances and Code Engine apps and jobs from the Service bindings page.

Alternatively, you can also create and manage service bindings to specific apps and jobs from the specific Code Engine app or job page in the console. To work with service bindings within the context of your app or job, go to the Service bindings tab for your specific app or job.

Binding a service instance with a new service access secret (with an existing credential)

Suppose you want to create a service binding to bind a service instance to an app or job with a new service access secret that uses an existing service credential. The existing service credential might have been automatically generated by Code Engine, or the service credential might have been manually. For this example, create a service binding for the myjob job, with a new service access secret that uses an existing service credential.

After your project is in Active status, click the name of your project on the Code Engine Projects page.
From the Overview page, click Service bindings.
From the Service bindings page, click Create to create the binding.
Select the IBM service instance that you want to bind to your Code Engine app or job.
Select the Code Engine app or job that you want to bind to the service instance; for example, choose the myjob job.
Specify the service access secret to use with this binding. The service access secret stores the credential for the service binding. Notice that any previously defined service credential for your specific service instance, which is not associated with the app or job that you selected, is listed. If no service access secret currently exists, then you are creating a new secret. If a service access secret does exist, to create a new service access secret with a new service credential for this binding, select New secret. Complete the following steps.
1. Select the Role for the service instance credential.
2. Expand Advanced options.
3. Select the service credential to use with this service access secret.
4. (optional) Specify a custom prefix for the service binding. If you do not specify a custom prefix, Code Engine automatically generates a prefix. The prefix is used to distinguish environment variables that are created for this service binding.
Click Add to create the service binding.
Now that your service binding to your app or job is created from the console, you can view a list of all defined service bindings between service instances and Code Engine apps and jobs from the Service bindings page.

Binding a service instance with an existing service access secret

You can reuse service access secrets in service bindings. For a specific IBM Cloud service instance, you can reuse service access secrets with different apps or jobs. You cannot reuse a service access secret for the same app or job that the service access secret was originally created for. Since the service credential is stored within the service access secret, it is important to consider the following points:

You can have more than one app or job that is bound to the same IBM Cloud service instance with the same service access secret.
A service access secret cannot be reused in a service binding for the same app or job. However, you can reuse the same service access secret in a different app or job. Because a service access secret is associated with a specific IBM Cloud service instance, you can reuse only the service access secret in a different app or job, if you are binding to the same service instance.

Let's create a service binding to bind a service instance to a job that uses an existing service access secret. For example, create a service binding for the myjob job and choose an existing service access secret for a specific service instance.

After your project is in Active status, click the name of your project on the Code Engine Projects page.
From the Overview page, click Service bindings.
From the Service bindings page, click Create to create the binding.
Select the IBM service instance that you want to bind to your Code Engine app or job.
Select the Code Engine app or job that you want to bind to the service instance.
You can reuse an existing credential for the service access secret for a service binding to a specific IBM Cloud service instance with a different app or job. For this case, select Existing secret. Notice that any previously defined service credential for your specific service instance is listed, which is not associated with the app or job that you selected. Complete the following steps.
1. Review the list of existing secrets and select the secret that you want to use with this service binding.
2. (optional) Specify a custom prefix for the service binding. If you do not specify a custom prefix, Code Engine automatically generates a prefix. The prefix is used to distinguish environment variables that are created for this service binding.
Click Add to create the service binding.
Now that your service binding to your app or job is created from the console, you can view a list of all defined service bindings between service instances and Code Engine apps and jobs from the Service bindings page.

Binding a service instance to a Code Engine app, job, or function with the CLI

You can create a service binding that binds an existing service instance to a Code Engine app, job, or function with the CLI.

Before you begin

Create and work with a project.
Set up your Code Engine CLI environment.
Create the service instance that you want to bind to your Code Engine workload.

For example, to create an IBM Cloud Object Storage service instance (Lite plan):
```
ibmcloud resource service-instance-create my-object-storage cloud-object-storage lite global -g Default
```
Create a Code Engine workload.

Binding a service instance with a new credential

To bind your new service instance to your Code Engine app and generate a new service credential, use the ibmcloud ce application bind command.
To bind your service instance to a Code Engine job, use the ibmcloud ce job bind command.
To bind your service instance to a Code Engine function, use the ibmcloud ce function bind command.

To create an app to use for these steps, run the following command.

ibmcloud ce application create --name my-application --image icr.io/codeengine/hello

Identify the name of the service instance that you want to bind to your app, job, or function. You can find all the service instances that are in your account for your current resource group by running the ibmcloud resource service-instances command; for example,
```
ibmcloud resource service-instances
```
Example output
```
Name                               Location   State    Type               Resource Group ID
my-object-storage                  global     active   service_instance   325d80be5d7945608f6d121712c96ee9
```

Bind your service instance to your Code Engine app, job, or function and generate a new service credential with the default service role. The default service role is either Manager or the first role that is provided by the service if Manager is not supported. In the following example, application bind command binds the my-object-storage service instance with the app called my-application. A new service credential with the Manager role is generated for this binding action.

ibmcloud ce application bind --name my-application --service-instance my-object-storage

The following table summarizes the options that are used with the application bind command in this example. For more information about the command and its options, see the ibmcloud ce application bind command.

Table 1. Command options
Option	Description
`--name`	The name of the application to bind. This value is required.
`--service-instance`	Specify the name of an existing service instance to bind to the application. This value is required.

Example output

Binding service instance...
Status: Done
Waiting for application revision to become ready...
The Configuration is still working to reflect the latest desired specification.
Traffic is not yet migrated to the latest revision.
Ingress has not yet been reconciled.
Waiting for load balancer to be ready.
OK

Verify that the credentials were generated by using the application get, the job get, or the function get command. In the following example, verify that the credentials that were created in the previous example were created.

ibmcloud ce application get --name my-application

Example output

[...]
Service Bindings:
Name                                         ID                                    Service Instance      Service Type          Role / Credential  Environment Variable Prefix
my-application-app-ce-service-binding-abcde  abcde5d3-dfc3-4f52-b133-b869b5eabcde  my-object-storage     cloud-object-storag   Writer             CLOUD_OBJECT_STORAGE
[...]

Binding a service instance with a specific role

To bind your new service instance to your Code Engine app and generate a new service credential, use the ibmcloud ce application bind command.
To bind your service instance to a Code Engine job, use the ibmcloud ce job bind command.
To bind your service instance to a Code Engine function, use the ibmcloud ce function bind command.

To create a function to use for these steps, run the following command.

ibmcloud ce function create --name myfun --runtime nodejs-18 --build-source https://github.com/IBM/CodeEngine --build-context-dir /helloworld-samples/function-nodejs

Identify the name of the service instance that you want to bind to your app, job, or function. You can find all the service instances that are in your account for your current resource group by running the ibmcloud resource service-instances command; for example,
```
ibmcloud resource service-instances
```
Example output
```
Name                               Location   State    Type               Resource Group ID
my-object-storage                  global     active   service_instance   325d80be5d7945608f6d121712c96ee9
```

Bind your service instance to your Code Engine app, job, or function and generate a new service credential with a specific service role. For more information about IAM service roles, see Service access roles. In the following example, the function bind command binds the my-object-storage service instance to the function called my-function by using the Writer service role. A new service credential with the Writer role is generated for this binding action. By specifying the --prefix option, a prefix is added to the environment variables that are created by the service bindings.

ibmcloud ce function bind --name my-function --service-instance my-object-storage --role Writer --prefix MYPREFIX

The following table summarizes the options that are used with the function bind command in this example. For more information about the command and its options, see the ibmcloud ce function bind command.

Table 2. Command options
Option	Description
`--name`	The name of the function to bind. This value is required.
`--prefix`	The prefix for environment variables that are created for this service binding. For example, `--prefix MYPREFIX` adds the `MYPREFIX` prefix to any environment variables that are created for this service binding. For more information, see prefix method.
`--service-instance`	Specify the name of an existing service instance to bind to the function. This value is required.
`--role`	The name of a service role for the new service credential that is created for this service binding. Valid values include `Reader`, `Writer`, `Manager`, or a service-specific role. If the `--role` option is not specified, the default is `Manager` or the first role that is provided by the service if `Manager` is not supported. This option is ignored if `--service-credential` is specified.

Example output

Binding service instance...
Status: Done
OK

Verify that the credentials were generated by using the application get, the job get command, or the function get command . In the following example, verify that the credentials that were created in the previous example were created.

ibmcloud ce function get --name my-function

Example output

[...]
Service Bindings:
Name                                  ID                                    Service Instance      Service Type          Role / Credential  Environment Variable Prefix
my-function-ce-service-binding-abcde  abcde5d3-dfc3-4f52-b133-b869b5eabcde  my-object-storage     cloud-object-storage  Writer             MYPREFIX                     30s 
[...]

Binding a service instance with existing credentials

If you already created a credential for your service instance and want to use it for your service binding, add the --service-credentials option.

To create a job to use for these steps, run the following command.

ibmcloud ce job create --name my-job --image icr.io/codeengine/hello

Identify the name of the service instance that you want to bind to your app, job, or function. You can find all the service instances that are in your account for your current resource group by running the ibmcloud resource service-instances command; for example,
```
ibmcloud resource service-instances
```
Example output
```
Name                               Location   State    Type               Resource Group ID
my-object-storage                  global     active   service_instance   325d80be5d7945608f6d121712c96ee9
```
Find the credentials of the service instance.
```
ibmcloud resource service-keys --instance-name INSTANCENAME
```
Example output
```
Name                State    Created At       
my-cos-credential   active   Tue Mar  2 01:15:33 UTC 2021
```
To see details of a service credential, run ibmcloud resource service-key KEYNAME. You can find all the service keys in your resource group by running ibmcloud resource service-keys.

Bind the service instance to the app, job or function with existing credentials. For example, the following job bind command binds the my-object-storage service instance with existing service credentials called my-cos-credential to an existing job that is called myjob.

ibmcloud ce job bind --name myjob --service-instance my-object-storage --service-credential my-cos-credential

The following table summarizes the options that are used with the job bind command in this example. For more information about the command and its options, see the ibmcloud ce job bind command.

Table 3. Command options
Option	Description
`--name`	The name of the job to bind. This value is required.
`--service-instance`	Specify the name of an existing service instance to bind to the job. This value is required.
`--service-credential`	The name of the existing service credential to bind.

ibmcloud ce job get --name myjob

Example output

[...]
Service Bindings:
Name                                 ID                                    Service Instance      Service Type          Role / Credential  Environment Variable Prefix
myjob-ce-service-binding-abcde       abcde645-d3f9-407d-b964-6c3ae69abcde  my-object-storage  cloud-object-storage  my-cos-credential  CLOUD_OBJECT_STORAGE
[...]

Unbinding service instances

Unbinding service instances from an app, job, or function workloads removes existing service bindings.

When you unbind (or remove) a service binding, you are deleting the association of the app, job, or function workload with the service access secret such that the workload no longer has access to previously bound IBM Cloud service.

After a service binding is defined between your application and a service instance, the service binding is active as long as the application 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.

Unbinding a service instance from the console

From the Code Engine Projects page, go to your project.
From the Overview page, click Service bindings to view a listing of all defined service bindings. Or, if you want to manage service bindings from the context of your app or job, from the Overview page, click Applications or Jobs and click the name of your app or job. From the specific app or job page, go to the Service bindings tab.
From the list of service bindings, delete the binding that you want to remove from your app or job. Click the Actions icon > Delete to delete the service binding.

Unbinding a service instance with the CLI

Find the service binding that you want to remove with the application get, job get, or the function get command; for example,

ibmcloud ce application get --name my-application

Example output

[...]
Service Bindings:
Name                                         ID                                    Service Instance      Service Type          Role / Credential  Environment Variable Prefix
my-application-app-ce-service-binding-abcde  abcde5d3-dfc3-4f52-b133-b869b5eabcde  my-object-storage     cloud-object-storage  Writer             CLOUD_OBJECT_STORAGE
[...]

Remove the service binding by using the application unbind, job unbind, or function unbind command.
- To remove a single binding, specify the --name and --binding options.
```
ibmcloud ce application unbind --name APPLICATION_NAME --binding BINDING_NAME
```
- To unbind all service instances, use the --all option.
```
ibmcloud ce job unbind --name JOB_NAME --all
```