Deploying Voice Gateway in IBM Cloud Private

Important: Starting with IBM Voice Gateway 1.0.6, IBM Cloud Private is no longer supported. If you want to deploy the service on premises, deploy it in IBM Cloud Pak for Data instead.

You can run IBM® Voice Gateway in a private cloud by deploying it in IBM® Cloud Private. IBM Cloud Private is an integrated environment for managing containers that includes the container orchestrator Kubernetes, a private image repository, a management console, and monitoring frameworks.

IBM Cloud Private uses Helm charts to manage product deployments to Kubernetes. For more information, see Managing charts and apps. The Helm charts that you use to deploy Voice Gateway are hosted along with other products in the IBM / charts GitHub repository. The readme file in the repository contains additional information about using the charts.

You can deploy applications into IBM Cloud Private through the Catalog user interface or by using the Helm command-line interface.

Before you begin

• Learn about the basic deployment path in Getting started with Voice Gateway.

• Install IBM Cloud Private Version 3.1 or later on the system where Voice Gateway will be deployed. For detailed instructions, see Installing in the IBM Cloud Private documentation.

  • To try it out or set up a test environment, install IBM Cloud Private-CE (Community Edition) from Docker Hub.
  • For production environments, install IBM Cloud Private or IBM Cloud Private Enterprise from IBM Passport Advantage®.

(Required) Configure watson services:

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

   1. Speech to Text
   2. Text to Speech (self-service only)
   3. Watson Assistant (self-service only)

   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 the sample.voice.gateway GitHub repository. To learn more about importing JSON files, see Creating workspaces 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.

2. Install and configure the kubectl CLI so that you can access your Kubernetes cluster in IBM Cloud Private from the command line.

(Required if not using the default namespace) Configure namespace and PodSecurityPolicy:

• This chart requires a PodSecurityPolicy to be bound to the target namespace prior to installation, if using a non-default namespace. Choose either a predefined PodSecurityPolicy or have your cluster administrator create a custom PodSecurityPolicy for you.
  • If you're using IBM Cloud Private Version 3.1.2 or later, the predefined PodSecurityPolicy ibm-anyuid-hostaccess-psp has been verified for this chart, if your target namespace is bound to PodSecurityPolicy ibm-anyuid-hostaccess-psp you can proceed to install the chart.
  • If you're using IBM Cloud Private Version lower than 3.1.2, the cluster administrator will need to either manually create the following resources, or use the configuration scripts to create and delete the resources.

Custom PodSecurityPolicy

• Custom PodSecurityPolicy definition:

  apiVersion: extensions/v1beta1
  kind: PodSecurityPolicy
  metadata:
    name: ibm-voice-gateway-psp
  spec:
    privileged: false
    hostNetwork: true
    hostPorts:
    - min: 0
      max: 65535
    allowPrivilegeEscalation: false
    runAsUser:
      rule: MustRunAsNonRoot
    seLinux:
      rule: RunAsAny
    supplementalGroups:
      rule: 'MustRunAs'
      ranges:
        - min: 1
          max: 65535
    fsGroup:
      rule: 'MustRunAs'
      ranges:
        - min: 1
          max: 65535
    volumes:
    - 'configMap'
    - 'downwardAPI'
    - 'emptyDir'
    - 'persistentVolumeClaim'
    - 'secret'
    - 'projected'
  

• Custom ClusterRole for the custom PodSecurityPolicy:

  apiVersion: rbac.authorization.k8s.io/v1
  kind: ClusterRole
  metadata:
    name: ibm-voice-gateway-clusterrole
  rules:
  - apiGroups:
    - extensions
    resources:
    - podsecuritypolicies
    resourceNames:
    - ibm-voice-gateway-psp
    verbs:
    - use
  

Configuration scripts for custom PodSecurityPolicy:

• Download the following scripts from the prereqs directory.

  If you're using the Voice Gateway Production Helm Chart from IBM Passport Advantage, you can find the following scripts in pak_extensions/prereqs directory of the downloaded archive.

  • createSecurityClusterPrereqs.sh: Creates the PodSecurityPolicy and ClusterRole for all releases of this chart.
  • createSecurityNamespacePrereqs.sh: Creates the RoleBinding for the namespace. This script takes one argument; the name of a pre-existing namespace where the chart will be installed.
    • Example usage: ./createSecurityNamespacePrereqs.sh myNamespace
  • deleteSecurityClusterPrereqs.sh: Deletes the PodSecurityPolicy and ClusterRole for all releases of this chart.
  • createSecurityNamespacePrereqs.sh: Deletes the RoleBinding for the namespace. This script takes one argument; the name of the namespace where the chart was installed.
    • Example usage: ./deleteSecurityNamespacePrereqs.sh myNamespace

(Required) Configure tenant configuration secret:

1. Create a tenantConfig.json with the tenant credentials and any additional parameters. A sample tenantConfig.json can be found in the tenantConfig.json file.

   Visit Advanced JSON configuration for more information.

2. Create a secret vgw-tenantconfig-secret from the tenantConfig.json file using the following command:

   kubectl create secret generic vgw-tenantconfig-secret --from-file=tenantConfig=tenantConfig.json -n <namespace>
   

   Make sure to use the namespace you want to deploy this chart in.

(Required) Create metering API Key Secret:

1. Complete the steps mentioned on IBM® Cloud Private metering service page to create the Metering API Key.

   Make sure to create the API Key in the namespace you're going to deploy the helm chart.

2. Retrieve the Metering API Key:
   • After you have created the API Key, return to the IBM Cloud Private Management Console, open the menu and click Platform > Metering.
   • On the Metering dashboard, select Manage API Keys. Use this form to retrieve the metering API key that you created.
3. Add the generated API Key in a text file metering-api-key.txt (Make sure there are no extra spaces or new lines in the text file)
4. Create secret for the metering API Key:

   kubectl create secret generic metering-api-key-secret --from-file=meteringApiKey=metering-api-key.txt -n <namespace>
   

(Optional) Load Voice Gateway Production Helm Chart from IBM Passport Advantage

1. To load and install the IBM Voice Gateway (Production) Helm chart from IBM Passport Advantage, download the package from IBM Passport Advantage and follow the step in Installing bundled products.
2. Navigate through the list of Helm charts to the IBM Voice Gateway (Production) (ibm-voice-gateway-prod) Helm chart. The Helm chart description contains information about configuring and deploying Voice Gateway.

Optional Configurations

MRCPv2 configuration

• More info: Configuring services with MRCPv2
• Create unimrcpConfig secret from the unimrcpclient.xml file:

  kubectl create secret generic unimrcp-config-secret --from-file=unimrcpConfig=unimrcpclient.xml -n <namespace>
  

• If you changed the default MRCPv2 SIP Port, make sure to update that in the helm chart configuration also.
• Enable MRCP in the Helm Chart's Media Relay configuration before deployment

SSL configuration

• More info: Configuring SSL and TLS encryption

Adding trusted certificates for the SIP Orchestrator (For enabling SSL or Mutual Authentication):

• Create secret from the trust store key file:

  kubectl create secret generic trust-store-file-secret --from-file=trustStoreFile=myPKCS12File.p12 -n <namespace>
  

• Create secret for the SSL Passphrase:
  • Add passphrase in a text file ssl_passphrase.txt (Make sure there are no extra spaces or new lines in the text file)
  • Create secret from the text file:

    kubectl create secret generic ssl-passphrase-secret --from-file=sslPassphrase=ssl_passphrase.txt -n <namespace>
    

• Set type of the SSL file in the configuration
• Enable option Enable SSL or Mutual Authentication in the Helm Chart's SIP Orchestrator configuration before deployment

Adding trusted certificates for the Media Relay (For enabling SSL):

• Create secret from client CA certificate file:

  kubectl create secret generic client-ca-cert-secret --from-file=clientCaCertFile=ca-bundle.pem -n <namespace>
  

• Enable option Enable SSL in the Helm Chart's Media Relay configuration before deployment

Adding certificates for the Media Relay (For Mutual Authentication):

• Create secret from the SSL client PKCS12 file:

  kubectl create secret generic ssl-client-pkcs12-file-secret --from-file=clientPkcs12File=myPKCS12File.p12 -n <namespace>
  

• Create secret for the SSL Passphrase:
  • Add passphrase in a text file ssl_client_passphrase.txt (Make sure there are no extra spaces or new lines in the text file)
  • Create secret from the text file:

    kubectl create secret generic ssl-client-passphrase-secret --from-file=sslClientPassphrase=ssl_client_passphrase.txt -n <namespace>
    

• Enable option Enable Mutual Authentication in the Helm Chart's Media Relay configuration before deployment

Configuring secrets for proxy password for the Sip Orchestrator and the Media Relay:

• You can create the secret separately for the Sip Orchestrator and the Media Relay or use the same one.
• Create an individual text file with the Sip Orchestrator and the Media Relay proxy password. For example: so_proxy_password.txt and mr_proxy_password.txt (Make sure there are no extra spaces or new lines in the text file)
• To create the secret use one of the two ways:
  • Create separate secrets for each container:

    kubectl create secret generic so-proxy-password --from-file=soProxyPassword=so_proxy_password.txt -n <namespace>
    kubectl create secret generic mr-proxy-password --from-file=mrProxyPassword=mr_proxy_password.txt -n <namespace>
    

  • Create one secret for both containers:

    kubectl create secret generic proxy-password --from-file=soProxyPassword=so_proxy_password.txt --from-file=mrProxyPassword=mr_proxy_password.txt -n <namespace>
    

• Enter the secret name in the Proxy Password secret name field of the Helm Chart's configuration for the respective container or you can set the mediaRelayEnvVariables.proxyPasswordSecret and sipOrchestratorEnvVariables.proxyPasswordSecret variables during installation using Helm CLI.

Deploy Voice Gateway from the IBM Cloud Private Catalog

1. From the IBM Cloud Private dashboard, click Catalog.

2. Search/select the Voice Gateway Helm Chart.

   From the list of Helm Charts in the IBM Cloud Private Catalog

   1. Navigate through the list of Helm charts to the IBM Voice Gateway (Developer Trial) (ibm-voice-gateway-dev) Helm chart or IBM Voice Gateway (Production) (ibm-voice-gateway-prod) Helm chart. The Helm chart description contains information about configuring and deploying Voice Gateway. Select the Helm chart, and click Configure.

1. Enter a release name and select a namespace, which can be either the default namespace or a custom one. Also accept the license agreement for Voice Gateway.

2. The default number of replicas is set to 1. Deploying additional pods requires that you use a SIP load balancer. See Deploying additional pods.

3. If you need to edit any other parameters, click on the All parameters section. Tip: You can also change the Metering Server URL and IBM Cloud Private Master Node Domain/IP in this section.

4. Click Install to deploy Voice Gateway.

After Voice Gateway is deployed, you can view your deployment by going to the IBM Cloud Private navigation menu, select Workloads > Helm Releases.

Deploy Voice Gateway in IBM Cloud Private using the Helm CLI

1. Install and configure the kubectl CLI so that you can access your Kubernetes cluster in IBM Cloud Private from the command line.

2. Set up the Helm CLI, including all prerequisites. The CLI sets up the Helm client on your local machine to connect to the Tiller server in IBM Cloud Private. Important: You only need to install and initialize the Helm CLI. If you receive the expected output when you run the helm version --tls command to verify that the installation has initialized, you don't need to continue through the remaining steps.

3. Add the ibm-charts Helm repository by running the following command:

   helm repo add ibm-charts https://raw.githubusercontent.com/IBM/charts/master/repo/stable/
   

4. To install the chart with the release name my-release:

   helm install ibm-charts/ibm-voice-gateway-dev --name my-release --namespace <namespace>
   

   Replace ibm-voice-gateway-dev with ibm-voice-gateway-prod in the above command if using Production Helm Chart.

5. To specify any extra parameters you can use the --set option or create a yaml file with the parameters and specify it using the -f option on the command line.

   • For a complete list of supported parameters, please take a look at the table in Configuration section in the Helm README.

What to do next

After you deploy Voice Gateway, test your deployment as described in Getting started with Voice Gateway. To find the IP address of your deployment, on the IBM Cloud Private dashboard:

• Navigate to Workloads > Helm Releases and select your release name.
• Select the listed Deployment name.
• The host IP and pod IP are listed in the Pods section of the deployment page.

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

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. It's recommended that you encrypt the disk where you deploy Voice Gateway. 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.

Viewing information about your pods

After you start your Voice Gateway pods, you can view information about your pods through the IBM Cloud Private dashboard or from the command line.

• Get pod information from the command line:
  • Show all pods:

    kubectl get pods -n <namespace>
    

  • Get details about a certain pod:

    kubectl describe pod <pod name> -n <namespace>
    

Changing the configuration

You can change the configuration from within the IBM Cloud Private Catalog or from the command line. For a list of configuration parameters that you can change, see the Helm chart readme. Whenever you change the configuration, you must redeploy Voice Gateway for the change to take effect.

Important: Enabling features that require outside files, such as recording calls , require additional configuration changes to mount the files on a volume when you redeploy. For more information, see the documentation under Advanced configuration.

Deploying additional Voice Gateway pods

If you want to deploy additional Voice Gateway pods, you'll need to add more nodes to your cluster and deploy a SIP load balancer. To learn more about configuring Voice Gateway high availability, see Setting up high availability.