Deploying Voice Gateway to a Kubernetes cluster

Before you begin

• 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)
• Ensure you have access to your on-premises Kubernetes cluster
• Install and set up the kubectl command line tool
• 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.
• Set up image pull secrets to download the Voice Gateway images, see Accessing IBM Voice Gateway Images in Kubernetes or OpenShift.

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. You can create or import a workspace in the Watson Assistant Tool inside your Watson Assistant Service.

Deploying Voice Gateway to a Kubernetes cluster

To deploy and manage Kubernetes clusters, you'll typically use the kubectl command-line tool.

1. Define the configuration for the Kubernetes cluster in a JSON or YAML file.

   Tip: To quickly get started, copy and paste the contents of the deploy.json sample file into an empty JSON file. Then, edit the sample file and specify your Watson service credentials and Watson Assistant workspace ID.

   This sample file sets the following Kubernetes configuration:

   • It deploys one Voice Gateway pod on a single node, as defined by the value of the replicas attribute. Add more nodes by increasing the number of replicas. For high availability, a minimum of three Voice Gateway pods is recommended.
   • It enforces one pod per node. If the number of replicas is greater than the number of nodes, the extra replica to be scheduled remains in a waiting state rather than being deployed.
   • It exposes SIP and media relay ports on the associated VM by setting hostNetwork to true.
   • It automatically restarts any failed containers.

2. In the same directory, open the deploy.json Kubernetes deployment file, which 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.

   Fill in the following Watson service credentials as required by your Voice Gateway implementation.

   Important: Make note of the apikeys for the services, but don't specify them in the file. To secure your credentials, you will create a Kubernetes secret.

   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, this authentication page can help you.

   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"
   }
   

   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"
   }
   

3. 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.

4. Deploy your Kubernetes cluster by specifying your deployment configuration file on the kubectl create command.

   kubectl create -f deploy.json
   

   When your cluster is deployed, you'll see messages about the created volumes and deployments.

   persistentvolume "recordings" created
   persistentvolumeclaim "recordings" created
   deployment "vgw" created
   

5. Verify that your cluster is running with the kubectl get pods command.

   The command displays the status of all pods in your cluster.

   >kubectl get pods
   NAME                   READY     STATUS    RESTARTS   AGE
   vgw-4151379926-7xbz5   2/2       Running   0          6s
   vgw-4151379926-lvq87   2/2       Running   0          6s
   

What to do next

After you deploy the Voice Gateway to Kubernetes, test your deployment as described in Getting started with Voice Gateway. Or, you can configure your deployment to use the Optimal configuration settings for your release.

You can configure your deployment to Kubernetes for high availability in Setting up high availability.

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 when you deploy Voice Gateway. It's recommended that you encrypt the disk where Voice Gateway is deployed. Hard disk encryption can protect any recordings or text to speech responses that are cached in the file system, because they might contain sensitive information. Encrypting the hard disk only encrypts data stored in Voice Gateway. You must take additional steps to secure data in services that are integrated with Voice Gateway.