Adding services by using IBM Cloud service binding

What types of services can I bind to my cluster?

You can bind services that are enabled for IBM Cloud Identity and Access Management (IAM). IAM-enabled services offer more granular access control and can be managed in an IBM Cloud resource group. For more information, see Managing access to resources.

To find a list of supported IBM Cloud services, see the IBM Cloud catalog.

What is IBM Cloud service binding?

Service binding is a quick way to create service credentials for an IBM Cloud service by using its public cloud service endpoint and storing these credentials in a Kubernetes secret in your cluster. To bind a service to your cluster, you must provision an instance of the service first. Then, you use the ibmcloud oc cluster service bind command to create the service credentials and the Kubernetes secret. The Kubernetes secret is automatically encrypted in etcd to protect your data.

Want to make your secrets even more secured? Ask your cluster admin to enable a key management service provider in your cluster to encrypt new and existing secrets, such as the secret that stores the credentials of your IBM Cloud service instances.

I already have an IBM Cloud service. Can I still use IBM Cloud service binding?

Yes, you can use services that meet naming requirements and reuse the service credentials.

• Naming: Make sure that the service name is in the following regex format. Example permitted names are myservice or example.com. Characters that are not allowed include spaces and underscores.

  [a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*
  

• Service credentials: To use your existing service credentials, specify the --key option in the ibmcloud oc cluster service bind command and provide the name of your service credentials. IBM Cloud service binding automatically creates a Kubernetes secret with your existing service credentials.

What if I want to use service credentials that use the private cloud service endpoint?

By default, the ibmcloud oc cluster service bind command creates service credentials with the public cloud service endpoint. To use the private cloud service endpoint, you must manually create service credentials for your service that use the private cloud service endpoint, and then use the --key option to specify the name of the existing service credentials.

Your service might not yet support private cloud service endpoints.

Can I use all IBM Cloud services in my cluster?

You can use service binding only for services that support service keys so that the service credentials can automatically be created and stored in a Kubernetes secret. To find a list of services that support service keys, see Enabling external apps to use IBM Cloud services.

Services that don't support service keys usually provide an API that you can use in your app. The service binding method does not automatically set up API access for your app. Make sure to review the API documentation of your service and implement the API interface in your app.

Can I bind multiple IBM Cloud services to multiple clusters at once?

IBM Cloud service binding is on a per-cluster, per-service basis, and works by creating a Kubernetes secret that your pods can mount.

For multiple clusters and services, you can use IAM trusted profiles instead. In IAM, you create a trusted profile with access policies for the IBM Cloud services that you want. Then, you link the trusted profile with as many clusters as you want, based on conditions such as all the prod Kubernetes namespaces in clusters in a resource group. Finally, your pods mount the Kubernetes service account projected volume to get a token that can be exchanged for an IAM token that your apps use to authenticate with the IBM Cloud services.

Mounting the secret as a volume to your pod

When you mount the secret as a volume to your pod, a file that is named binding is stored in the volume mount directory. The binding file in JSON format includes all the information and credentials that you need to access the IBM Cloud service.

1. List available secrets in your cluster and note the name of your secret. Look for a secret of type Opaque. If multiple secrets exist, contact your cluster administrator to identify the correct service secret.

   oc get secrets
   

   Example output

   NAME                              TYPE            DATA      AGE
   binding-<service_instance_name>   Opaque          1         3m
   

2. Create a YAML file for your Kubernetes deployment and mount the secret as a volume to your pod.

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     labels:
       app: secret-test
     name: secret-test
     namespace: <my_project>
   spec:
     selector:
       matchLabels:
         app: secret-test
     replicas: 1
     template:
       metadata:
         labels:
           app: secret-test
       spec:
         containers:
         - image: icr.io/ibm/liberty:latest
           name: secret-test
           volumeMounts:
           - mountPath: <mount_path>
             name: <volume_name>
         volumes:
         - name: <volume_name>
           secret:
             defaultMode: 420
             secretName: binding-<service_instance_name>
   

   volumeMounts.mountPath

   The absolute path of the directory to where the volume is mounted inside the container.

   volumeMounts.name and volumes.name

   The name of the volume to mount to your pod.

   secret.defaultMode

   The read and write permissions on the secret. Use 420 to set read-only permissions.

   secret.secretName

   The name of the secret that you noted in the previous step.

3. Create the pod and mount the secret as a volume.

   oc apply -f secret-test.yaml
   

4. Verify that the pod is created.

   oc get pods
   

   Example CLI output:

   NAME                           READY     STATUS    RESTARTS   AGE
   secret-test-1111454598-gfx32   1/1       Running   0          1m
   

5. Access the service credentials.

   1. Log in to your pod.

      oc exec <pod_name> -it bash
      

   2. Navigate to your volume mount path that you defined earlier and list the files in your volume mount path.

      cd <volume_mountpath> && ls
      

      Example output

      binding
      

      The binding file includes the service credentials that you stored in the Kubernetes secret.

   3. View the service credentials. The credentials are stored as key value pairs in JSON format.

      cat binding
      

      Example output

      {"apikey":"<API_key>","host":"<ID_string>-bluemix.cloudant.com","iam_apikey_description":"Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloudantnosqldb:us-south:a/<ID_string>:<ID_string>::","iam_apikey_name":"auto-generated-apikey-<ID_string>","iam_role_crn":"crn:v1:bluemix:public:iam::::serviceRole:Writer","iam_serviceid_crn":"crn:v1:bluemix:public:iam-identity::a/<ID_string>::serviceid:ServiceId-<ID_string>","password":"<ID_string>","port":443,"url":"https://<ID_string>-bluemix.cloudant.com","username":"123b45da-9ce1-4c24-ab12-rinwnwub1294-bluemix"}
      

   4. Configure your app to parse the JSON content and retrieve the information that you need to access your service.

Referencing the secret in environment variables

You can add the service credentials and other key value pairs from your Kubernetes secret as environment variables to your deployment.

1. List available secrets in your cluster and note the name of your secret. Look for a secret of type Opaque. If multiple secrets exist, contact your cluster administrator to identify the correct service secret.

   oc get secrets
   

   Example output

   NAME                              TYPE            DATA      AGE
   binding-<service_instance_name>   Opaque          1         3m
   

2. Get the details of your secret to find potential key value pairs that you can reference as environment variables in your pod. The service credentials are stored in the binding key of your secret.

   oc get secrets binding-<service_instance_name> --namespace=<project> -o yaml
   

   Example output

   apiVersion: v1
   data:
     binding: <binding>
   kind: Secret
   metadata:
     annotations:
       service-instance-id: 7123acde-c3ef-4ba2-8c52-439ac007fa70
       service-key-id: 9h30dh8a-023f-4cf4-9d96-d12345ec7890
     creationTimestamp: 2018-08-07T20:47:14Z
     name: binding-<service_instance_name>
     namespace: <project>
     resourceVersion: "6145900"
     selfLink: /api/v1/namespaces/default/secrets/binding-mycloudant
     uid: 12345a31-9a83-11e8-ba83-cd49014748f
   type: Opaque
   

3. Create a YAML file for your Kubernetes deployment and specify an environment variable that references the binding key.

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     labels:
       app: secret-test
     name: secret-test
     namespace: <my_project>
   spec:
     selector:
       matchLabels:
         app: secret-test
     template:
       metadata:
         labels:
           app: secret-test
       spec:
         containers:
         - image: icr.io/ibm/liberty:latest
           name: secret-test
           env:
           - name: BINDING
             valueFrom:
               secretKeyRef:
                 name: binding-<service_instance_name>
                 key: binding
   

   containers.env.name

   The name of your environment variable.

   env.valueFrom.secretKeyRef.name

   The name of the secret that you noted in the previous step.

   env.valueFrom.secretKeyRef.key

   The key that is part of your secret and that you want to reference in your environment variable. To reference the service credentials, you must use the binding key.

4. Create the pod that references the binding key of your secret as an environment variable.

   oc apply -f secret-test.yaml
   

5. Verify that the pod is created.

   oc get pods
   

   Example CLI output:

   NAME                           READY     STATUS    RESTARTS   AGE
   secret-test-1111454598-gfx32   1/1       Running   0          1m
   

6. Verify that the environment variable is set correctly.

   1. Log in to your pod.

      oc exec <pod_name> -it bash
      

   2. List all environment variables in the pod.

      env
      

      Example output

      BINDING={"apikey":"<API_key>","host":"<ID_string>-bluemix.cloudant.com","iam_apikey_description":"Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloudantnosqldb:us-south:a/<ID_string>::","iam_apikey_name":"auto-generated-apikey-<ID_string>","iam_role_crn":"crn:v1:bluemix:public:iam::::serviceRole:Writer","iam_serviceid_crn":"crn:v1:bluemix:public:iam-identity::a/1234567890brasge5htn2ec098::serviceid:ServiceId-<ID_string>","password":"<password>","port":443,"url":"https://<ID_string>-bluemix.cloudant.com","username":"<ID_string>-bluemix"}
      

7. Configure your app to read the environment variable and to parse the JSON content to retrieve the information that you need to access your service.

   Example code in Python:

   if os.environ.get('BINDING'):
       credentials = json.loads(os.environ.get('BINDING'))
   

8. Optional: As a precaution, add error handling to your app in case that the BINDING environment variable is not set properly.

   Example code in Java:

   if (System.getenv("BINDING") == null) {
   throw new RuntimeException("Environment variable 'SECRET' is not set!");
   }
   

   Example code in Node.js:

   if (!process.env.BINDING) {
   console.error('ENVIRONMENT variable "BINDING" is not set!');
   process.exit(1);
   }