GitHubContribute in GitHub: Edit online

copyright: years: 2017, 2023 lastupdated: "2023-01-03"

Deploying Voice Gateway to Kubernetes in IBM Cloud Kubernetes Service

You can run IBM® Voice Gateway in the cloud by deploying it to a Kubernetes cluster 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:

    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


1. 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](https://www.ibm.com/docs/en/voice-gateway?topic=reference-configuration-environment-variables).

  1. Edit the `deploy.json` file by filling in the following [Watson service credentials](https://cloud.ibm.com/docs/watson?topic=watson-iam#getting-credentials-manually) 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 (**&vellip;**) and select **View details**.

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

    For example:
    ```json
    {
        "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](https://www.ibm.com/docs/en/voice-gateway?topic=gateway-authenticating-connected-services) 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](https://www.ibm.com/docs/en/voice-gateway?topic=gateway-securing-voice#whitelisting-callers-and-callees).

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

 3. If you're implementing an agent assistant, configure [transcription reporting events](https://www.ibm.com/docs/en/voice-gateway?topic=events-reporting-transcription).

    For example:
    ```json
    {
      "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"
    }
    ```
2. 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
  ```
  {:codeblock}

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

3. 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
  ```
  {:codeblock}
  Running this command deploys one Voice Gateway pod on a single worker node within a Kubernetes cluster.


## What to do next {: #next}

After you deploy the Voice Gateway in IBM Cloud Kubernetes Service, test your deployment as described in [Getting started with Voice Gateway](https://www.ibm.com/docs/en/voice-gateway?topic=gateway-getting-started). 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](https://kubernetes.io/docs/user-guide/kubectl-overview/), 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](https://www.ibm.com/docs/en/voice-gateway?topic=reference-configuration-environment-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](https://www.ibm.com/docs/en/voice-gateway?topic=reference-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](https://cloud.ibm.com/docs/containers?topic=containers-security#encrypted_disks). 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.

### Viewing information about your pods {: #viewing-info}

After you start your Voice Gateway pods, you can view information about your pods through the Kubernetes dashboard or from the command line.
* To view the Kubernetes Dashboard, run the `kubectl proxy` command, and then open `http://localhost:8001/ui/` in your browser.
* Get pod information from the command line:
 * Show all pods:

kubectl get pods

{:codeblock}
* Get details about a certain pod:

kubectl describe pod pod1

{:codeblock}

### Deploying additional Voice Gateway pods {: #add-pods}

If you want to deploy additional Voice Gateway pods, you'll need to move to a standard Kubernetes cluster in IBM Cloud and add more nodes to your cluster, because you can run only a single Voice Gateway pod per node. Then, change the `replicas` value in the `deploy.json` file to less than or equal to the number of nodes. If you deploy multiple Voice Gateway pods, you also need to deploy a SIP load balancer, such as [Citrix NetScaler VPX Dedicated Load Balancer in IBM Cloud](https://www.ibm.com/cloud-computing/bluemix/load-balancer-services).

To learn more about configuring Voice Gateway high availability, see [Setting up high availability](https://www.ibm.com/docs/en/voice-gateway?topic=gateway-setting-up-high-availability).