Deploying SMS Gateway to Kubernetes in IBM Cloud Kubernetes Service

Before you begin

• Create a phone number with SMS capabilities and create the IBM Watson™ Assistant service as described in Getting started with SMS Gateway.

• Clone or download the sample.voice.gateway repository on GitHub. This repository contains sample files for deploying SMS Gateway, such as a Kubernetes deployment file and service policy.

• Sign up for an IBMid and IBM Cloud account, and create a IBM Watson™ Assistant service instance. (self-service only)

  Remember: Make note of the credentials. You'll need to specify the credentials in the SMS Gateway configuration.

• Also in IBM Cloud, create a Kubernetes cluster in IBM® Cloud Kubernetes Service. For more information about setting up your cluster, see the IBM Cloud Kubernetes Service.

  Note: Lite clusters are available for a limited free trial period of 30 days, and the cluster is automatically removed after the trial period ends. Be sure to use standard clusters for production deployments. For more information, see the cluster comparison information in the IBM Cloud Kubernetes Service documentation.

Deploying SMS Gateway in IBM Cloud Kubernetes Service

1. Configure the following CLI tools so that you can access your Kubernetes cluster on IBM Cloud through the command line.

   1. Install the IBM Cloud CLI, which is required to interact with IBM Cloud Kubernetes Service from the command line.
   2. Install the IBM Cloud Kubernetes Service plug-in (ibmcloud ks) and Kubernetes CLI.

   The IBM Cloud Kubernetes Service plug-in (ibmcloud ks) is needed to manage your SMS Gateway clusters from the command line. The Kubernetes CLI enables you to use native Kubernetes commands to interact with IBM Cloud.

   1. Configure the IBM Cloud CLI to run kubectl commands.

   After you configure the CLI, you can run the Kubernetes kubectl commands to work with your SMS Gateway cluster in IBM Cloud.

2. Open the sms/kubernetes/bluemix/single-tenant or sms/kubernetes/bluemix/multi-tenant directory in your local clone of the sample.voice.gateway repository. Copy the contents to a new directory from which you want to deploy SMS Gateway.

3. In the same directory, open the deploy.json Kubernetes deployment file, which contains the configuration information for the SMS Gateway container. The env object contains a list of name-value pairs, which each correspond with the configuration environment variables.

   Note: The following examples show a single-tenant configuration. If you're using a multi-tenant configuration, open the deploy-multi-tenant.json and configure your tenant service credentials, conversation, smsProvider, and tenantPhoneNumber. See Configuring tenants in a multi-tenant SMS Gateway JSON configuration.

   • For Watson Assistant, specify the service credentials and workspace ID. For information about how to find the service credentials, see Service credentials for Watson services.

   Tip: To find the Watson Assistant workspace ID, go to the Workspaces view within the Watson Assistant tool. On the workspace that you want to integrate, click the Actions icon (⋮) and select View details.

   For example:

   {
     "name": "WATSON_CONVERSATION_URL",
     "value": "https://api.us-south.assistant.watson.cloud.ibm.com/instances/{instance_id}"
   },{
     "name":"WATSON_CONVERSATION_WORKSPACE_ID",
     "value":"2346v425-ya4v-26hj-5hu6-wf57b9fc253c"
   },{
     "name":"WATSON_CONVERSATION_TOKEN_SERVICE_PROVIDER_URL",
     "value":"https://iam.cloud.ibm.com/identity/token"
   },{
     "name":"WATSON_CONVERSATION_APIKEY",
     "valueFrom": {
         "secretKeyRef": {
             "name": "secret-creds",
             "key": "WATSON_CONVERSATION_APIKEY"
         }
     }
   }
   

   • For the SMS provider, specify the API URL and login credentials.

     The user name maps to the account SID, and the password maps to the authentication token. You can find both of these values on the console for your SMS provider.

     For example:

     {
      "name": "SMS_PROVIDER_URL",
      "value": "https://api.twilio.com"
     }, {
      "name": "SMS_PROVIDER_USERNAME",
      "value": "23de67h0236e5e7c7f1ead4499h7f54cb"
     }, {
      "name": "SMS_PROVIDER_PASSWORD",
      "value": "9h7f54cb3b1d3736e19ac64aa23de67h"
     }
     

   • For the tenant phone number, specify the full phone number from your SMS provider.

     Use the exact number format that the SMS provider requires. For example, to specify a Twilio phone number, include a plus sign (+) and the country and area codes. For RestcommONE, don't include the plus sign (+).

     For example:

     {
      "name": "TENANT_PHONE_NUMBER",
      "value": "+12345556789"
     }
     

   • Optional: If you want to allow users to create SMS sessions by sending an SMS message to the gateway, set ALLOW_SESSION_CREATE_VIA_SMS to true. By default, SMS sessions can only be created by using the REST API.

   For example:

   {
    "name": "ALLOW_SESSION_CREATE_VIA_SMS",
    "value": "true"
   }
   

4. After cluster is ready, set the context for your local CLI to your cluster by using a KUBECONFIG environment variable. Use this environment variable to run the kubectl commands to work with the cluster.

   1. Log in to IBM Cloud.

   ibmcloud login --sso
   

   1. Run the following command to retrieve the path that you can use for your KUBECONFIG environment variable from your IBM Cloud Kubernetes Service service.

   ibmcloud cs cluster-config <cluster_name_or_id> --admin
   

   1. Export the KUBECONFIG variable by using the path that you retrieved for your IBM Cloud Kubernetes Service cluster. The following example shows what your kube configuration might look like.

   export KUBECONFIG=/root/.bluemix/plugins/container-service/clusters/<cluster_name_or_id>-admin/kube-config-xxxx-<cluster_name_or_id>.yml
   

   1. Apply the service.yaml file, which you can find in the repository where you copied your clone of the SMS Gateway sample.

   kubectl apply -f service.yaml
   

5. Create a Kubernetes secret to store the password credentials for your Watson service instances. To create the secret, run the kubectl create secret generic secret-creds command, and use the --from-literal option to specify the environment variable and password credential for your Watson Assistant service. The following example shows how to generate a secret for a single-tenant deployment.

   kubectl create secret generic secret-creds  --from-literal=WATSON_CONVERSATION_APIKEY='prqNfi8Dsj'
   

   Service passwords for multi-tenant deployments are stored in the tenant configuration file, tenantconfig/tenantConfig.json. If you use a multi-tenant configuration, create a Kubernetes secret with --from-file. See Configuring tenants in a multi-tenant SMS Gateway JSON configuration for information about configuring service password credentials.

   kubectl create secret generic secret-tenantconfig --from-file=tenantconfig/tenantConfig.json
   

   This secret can be reused each time you redeploy SMS Gateway. You only need to recreate the secret if you change service instances. To see a list of the secrets that you created, use the kubectl get secrets command.

6. Create a Kubernetes pod that contains the SMS Gateway containers by specifying your deployment file on the kubectl create command.

   kubectl create -f deploy.json
   

   Running this command deploys one SMS Gateway pod on a single worker node within a Kubernetes cluster. If you want to use a multi-tenant deployment, use the deploy-multi-tenant.json deployment file instead of deploy.json.

7. Find the public IP address to run your deployment.

   ibmcloud cs workers <cluster_name_or_id>
   

What to do next

After you deploy SMS Gateway in IBM Cloud Kubernetes Service, set up a webhook and test your deployment as described in Getting started with SMS Gateway. You can run the ibmcloud ks workers myClusterName command to determine the public IP address.

If you're not familiar with using kubectl to interact with Kubernetes clusters, learn more in the Kubernetes documentation, which includes a kubectl cheatsheet.

You can further configure your SMS Gateway deployment by editing the deploy.json or deploy-multi-tenant.json file to add or change configuration variables, and then redeploying your pod.