Deploying Voice Gateway to Kubernetes in IBM Cloud Kubernetes Service

Before you begin

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

• Sign up for an IBMid and IBM Cloud account, and create the following Watson services:

  • Speech to Text
  • Text to Speech (self-service only)
  • IBM Watson™ Assistant (self-service only)

  Make note of the credentials for each service that you created. You'll need to specify the credentials in the Voice Gateway configuration.

  Important: For Watson Assistant, you'll need to add a workspace with a dialog. You can quickly get started by importing the conversation/sample-conversation-en.json file from your cloned sample.voice.gateway GitHub repository. To learn more about importing JSON files, see Creating a dialog skill in the Watson Assistant documentation. If you build your own dialog instead of using the sample, ensure that your dialog includes a node with the conversation_start condition and node with a default response.

• 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 documentation.

  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 Voice Gateway on a Kubernetes cluster in IBM Cloud

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 Voice 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 Voice Gateway cluster in IBM Cloud.

   1. Install and configure the Calico CLI so that you can use the calicoctl commands to change the default network policies.

   Network policies specify the network traffic that you want to allow or block to and from a pod in a cluster.

2. Change to either the single-tenant or multi-tenant directory under the kubernetes/bluemix directory in your local clone of the sample.voice.gateway repository. Then, apply the sample Calico network policy.

   #change to the directory
   cd sample.voice.gateway/kubernetes/bluemix/<YOUR_CHOICE_OF_SINGLE_OR_MULTI_TENANT>
   calicoctl apply -f calico-v3.yaml
   

3. In the same directory, open the Kubernetes deployment file.

   • V1.0.2.0 and later: Open the deploy.json file.
   • Before V1.0.2.0: Rename the deploy-vgw-v100x.json file to the deploy.json file, and then open the deploy.json file.

   The deployment file contains the configuration information for the Media Relay (vgw-media-relay) and SIP Orchestrator (vgw-sip-orchestrator) containers. The env object for each container contains a list of name-value pairs, which each correspond with the configuration environment variables.

   1. Edit the deploy.json file by filling in the following Watson service credentials as required by your Voice Gateway implementation.

      In the vgw-media-relay container, fill in all of these values:

      • Speech to Text: WATSON_STT_URL
      • Text to Speech (self-service only): WATSON_TTS_URL

      In the vgw-sip-orchestrator container, fill in the Watson Assistant values:

      • Watson Assistant (self-service only):WATSON_CONVERSATION_WORKSPACE_ID, WATSON_CONVERSATION_URL

      To find the Watson Assistant workspace ID, go to the Workspaces view within the Watson Assistant tool. Choose the assistant and on the skill that you want to use, click the Actions icon (⋮) and select View details.

      Important: Do not specify apikeys in the file. To secure your credentials, you will create a Kubernetes secret.

      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_APIKEY",
         "valueFrom": {
             "secretKeyRef": {
                 "name": "secret-creds",
                 "key": "WATSON_CONVERSATION_APIKEY"
             }
         }
      }
      

      If you're running into problems filling out or finding these values, the authentication page can help you.

   2. If you already configured a SIP trunk or session border controller, define the WHITELIST_TO_URI value under the env object for the vgw-sip-orchestrator container. Whitelisting calls to your SIP trunk helps to prevent denial-of-service (DoS) attacks and other unwanted sessions from outside sources, which could incur unnecessary Watson service charges and affect Voice Gateway performance. For more information, see Whitelisting callers and callees.

   {
     "name": "WHITELIST_TO_URI",
     "value": "2345556789"
   }
   

   3. If you're implementing an agent assistant, configure transcription reporting events.

   For example:

   {
     "name": "REPORTING_URL",
     "value": "http://myresteventserver.ibm.com/"
   }, {
     "name": "REPORTING_USERNAME",
     "value": "myRestAdmin"
   }
   {
     "name": "REPORTING_PASSWORD",
     "value": "myRestTokenOrPassword"
   }, {
     "name": "REPORTING_TRANSCRIPTION_EVENT_INDEX",
     "value": "transcription"
   }
   

4. 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 each of the following services.

   • Speech to Text: WATSON_STT_APIKEY
   • Text to Speech (self-service only): WATSON_TTS_APIKEY
   • Watson Assistant (self-service only): WATSON_CONVERSATION_APIKEY

   The following code shows an example of the secret.

   kubectl create secret generic secret-creds
   --from-literal=WATSON_STT_APIKEY=aaaBBBcc2hskx44mdcdd_Ind3
   --from-literal=WATSON_TTS_APIKEY=aaaBBBcc2hskx44mdcdd_Ind3
   --from-literal=WATSON_CONVERSATION_APIKEY=aaaBBBcc2hskx44mdcdd_Ind3
   

   This secret can be reused each time you redeploy Voice Gateway. You only need to recreate the secret if you change service instances.

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

   kubectl create -f deploy.json
   

   Running this command deploys one Voice Gateway pod on a single worker node within a Kubernetes cluster.

What to do next

After you deploy the Voice Gateway in IBM Cloud Kubernetes Service, test your deployment as described in Getting started with Voice Gateway. You can run the ibmcloud ks workers myClusterName command to determine the public Voice Gateway 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 Voice Gateway deployment by editing the deploy.json file to add or change configuration variables and then redeploying your pod. You can use the optimal configuration settings that are included in the most recent release by setting either the USE_OPTIMAL_CONFIGURATION environment variable. See Using optimal configuration settings.

Protecting sensitive information: Both the Text to Speech caching and audio recording collection are disabled by default. If you enable these features, take appropriate measures to protect and mitigate sensitive data that might be written on file system where Voice Gateway is deployed. When you deploy Voice Gateway to IBM Cloud, the data storage is automatically encrypted. See Security for IBM Cloud Kubernetes Service. Encryption can help protect sensitive information that might be produced through audio recordings or cached Text to Speech responses. IBM Cloud Kubernetes Service encryption only protects data in stored in the file system. You must take additional steps to secure data in services that are integrated with Voice Gateway.