Binding IBM Cloud services to Cloud Functions entities

Binding a service to an action or package

Bind any IBM Cloud service to any action. When a service is bound, a new parameter is created on your existing action that contains the service instance credentials.

You can bind only one instance of a service at a time and you cannot bind multiple instances of the same service to an action or package. You can bind a service to an individual action or you can bind a service to a package and then all actions that are contained in that package are bound to that service.

Before you begin, create an action and define credentials for the service that you want to bind to the action.

1. Get the list of available service keys of services that you want to bind to an action or package.

   ibmcloud resource service-keys
   

   Example output

   Name                             State    Created At
   Service credentials-1            active   Tue Sep 17 15:50:43 UTC 2019
   cloudant-my1-creds               active   Tue Sep 17 14:30:08 UTC 2019
   

   To find more details, use --output json.

   If you know the service name or ID, you can use the --instance-name NAME option to get only the subset of keys for a specific service instance. For example:

   ibmcloud resource service-keys --instance-name My-Cloudant
   

2. Get details of a selected service key.

   ibmcloud resource service-key <service_key_name>
   

   Example output

   Name:          cloudant-my1-creds
   ID:            crn:v1:bluemix:public:cloudantnosqldb:eu-de:a/123456789012345678901234567890ab:f6f38f72-95af-4699-842c-4cac2a1ea19e:resource-key:5dab35d4-fe20-433e-9cb9-7ae4d93887d5
   Created At:    Wed Nov 28 16:30:08 UTC 2018
   State:         active
   Credentials:
   apikey:  ABC123ABC123abc123abc123ABC123ABC123abc123
   ...
   

3. Bind the service to an action or package. The ibmcloud fn service bind command makes your IBM Cloud service credentials available to your Cloud Functions code at run time.

   Table 1. Parameters for the bind command

   Parameter	Description
   SERVICE	The service name that you're binding.
   ACTION_NAME	The name of the action or package that you want to bind the service to.
   --instance INSTANCE_NAME	(Optional) Specify a service instance name. If you don't specify a service instance name, the first instance for the service is selected.
   --keyname CREDENTIALS_NAME	(Optional) Specify the credentials name. If you don't specify the credentials name, the first credentials for the service instance are selected.

   Example syntax

   ibmcloud fn service bind SERVICE ACTION_NAME [--instance INSTANCE_NAME] [--keyname CREDENTIALS_NAME]
   

   For example, to bind an IBM Cloudant service instance to an action called hello, run the following command.

   ibmcloud fn service bind cloudantnosqldb hello --instance My-Cloudant --keyname cloudant-my1-creds
   

   If your action is not found, try adding the package name to the command: demo\hello. Note that if there's only one instance of service type cloudantnosqldb and one service key, the --instance and --keyname options can be omitted.

   If you receive the message Unable to refresh user access token: CloudFoundry API endpoint is not set, try running ibmcloud target --cf with no arguments and then running the command again.

   Example output

   Credentials 'cloudant-my1-creds' from 'cloudantnosqldb' service instance 'My-Cloudant' bound to 'hello'.
   

4. Verify that the credentials are successfully bound. The action that the service is bound to doesn't support any custom flags, but does support the debug and verbose flags.

   ibmcloud fn action get hello parameters
   

   Example output

   "key": "__bx_creds",
       "value": {
           "cloudantnosqldb": {
               "apikey": "ABC123ABC123abc123abc123ABC123ABC123abc123",
               "credentials": "cloudant-my1-creds",
               ...
           }
       }
   

   In this example, the credentials for the Cloudant service, along with any other credentials for other service types belong to a parameter named __bx_creds. The action code can access the necessary information by getting the __bx_creds parameter.

   For example, in nodejs, you can use the following code to get the API key for the Cloudant service in the previous sample.

   function main(params) {
       const apikey = params.__bx_creds.cloudantnosqldb.apikey; 
       // ...
       return { message: 'Hello done.' };
   }
   

For more information about passing parameters to an action or package, see Binding parameters to actions.

Binding Cloud Foundry based services

Cloud Foundry based services do not expose credentials through a service key resource, but instead use Cloud Foundry based service keys.

1. Find the name of the service and the service instance that you want to bind to an action or package. In the example output, composer is the service and Composer-qp is the service instance name.

   ibmcloud service list
   

   Example output

   name              service        plan   bound apps   last operation
   Composer-qp       composer       free                create succeeded
   Composer-uc       composer       free                create succeeded
   Discovery-37      discovery      lite                create succeeded
   

2. Get the name of the credentials that are defined for a service instance.

   ibmcloud service keys SERVICE_NAME
   

3. Bind the service to an action. The ibmcloud fn service bind command makes your IBM Cloud service credentials available to your Cloud Functions code at run time.

   Example syntax

   ibmcloud fn service bind SERVICE ACTION_NAME [--instance INSTANCE_NAME] [--keyname CREDENTIALS_NAME]
   

   For example, to bind an IBM Watson Composer service to an action named hello, run the following command.

   ibmcloud fn service bind composer hello --instance Composer-qp --keyname Credentials-1
   

   Example output

   Service credentials 'Credentials-1' from service 'Composer-qp' bound to action 'hello`.
   

4. Verify that the credentials are successfully bound. The action that the service is bound to doesn't support any custom flags, but does support the debug and verbose flags.

   ibmcloud fn action get hello parameters
   

   Example output

   ok: got action Hello World
   {
       "parameters": [
           {
               "key": "var1",
               "value": "val1"
           },
           {
               "key": "dog",
               "value": "cat"
           },
           {
               "key": "__bx_creds",
               "value": {
                   "composer": {
                   "password": "[Service password]",
                   "url": "[Service url]",
                   "username": "[Service username]",
                   "instance": "Composer-qp",
                   "credentials": "Credentials-1"
                   },
               }
           }
       ],
   }
   

   In this example, the credentials for the composer service, along with any other credentials for other service types belong to a parameter called __bx_creds. The action code can access the necessary information by getting the __bx_creds parameter.

For more information about passing parameters to an action or package, see Binding parameters to actions.

Unbinding services from actions

Unbinding a service from an action or package removes existing service bindings.

ibmcloud fn service unbind SERVICE_NAME ACTION_NAME