Deploying with Helm

This topic deploys VoiceXML Connector as a cloud-native container on Kubernetes with Helm.

The Helm charts do not include the following details. Your organization should handle these details before deploying VoiceXML Connector:

  • Network policies and firewalls
  • Method of entry load balancing/ingress (determine ingress into your cluster, which then points to Envoy-VxmlConnector)
  • Horizontal pod auto-scaling
  • Pod disruption budgets

Prerequisite software

Before you start, install the needed software products.

Note: For prerequisite versions, see the VoiceXML Connector release notes.

Needed software Description
Speech Suite

Required for all deployments.

VoiceXML browser

Required. VoiceXML Connector is tested with the Nuance platform add-on and browsers from Nuance partners.

Docker Required for cloud deployments.
Kubernetes cluster Required for cloud deployments.
Helm Required for cloud deployments.
Dialog service

Access required. Deploy in your cloud (self-hosted) or connect to a Nuance-hosted Dialog service.

The Dialog service must be accessible to VoiceXML Connector, and it requires access to a web server for fetching Mix dialog models. (The Connector does not use the ASR, TTS, or NLU services in the Dialog service. It uses the equivalent services from Speech Suite instead.)

Recommended. Include the optional CCSS service and configure a URN to the artifact server.

Note: When you create a Mix project, the versions of all dialog model components must be compatible with the your versions of the Dialog service, VoiceXML Connector, and Speech Suite. For details see Integrating with Speech Suite in the Nuance Mix documentation.

Redis server

Required. Redis server (Remote DIctionary Server) for persistent data storage. Install the latest bitnami/redis, and configure redis_config_name and redis_secret_name in VoiceXML Connector. For details, see Redis session configuration.

You can share the same data storage server with the Dialog service and VoiceXML Connector.

Recommended software

Recommended software Description
Log file monitoring

Recommended. Use an EFK stack to collect, store, and display log messages. Configure the stack to collect from the stdout stream.

Components of the EFK stack:

  • Elasticsearch-log storage.
  • Fluentd-log collector.
  • Kibana-web UI for viewing logs.

(Note: VoiceXML Connector logs diagnostic messages but not call events.)

Prometheus Recommended. Use Prometheus to monitor system runtime performance, detect alerts and fatal alarms, and to collect push metrics. It is enabled by default in the Helm configuration.
Grafana

Recommended. Use Grafana to collect and analyze metrics.

Jaegar

Recommended. Use Jaegar for detailed tracing and troubleshooting.

Installation procedure

  1. Install the prerequisite and recommended software (listed above) in any order.
  2. Download the product package from Nuance Network and extract it.
  3. From the Cloud folder, extract VxmlConnector-x.y.z.tar.gz (where x.y.z is the version). Contents:
    FileDescription
    VxmlConnector.tar Docker image, VoiceXML Connector
    Envoy-VxmlConnector.tar Optional Envoy Docker image. Recommended for load balancing.
    Vxmlconnector-x.y.z.tgz

    Helm Chart tar file

  4. Load the Docker and Envoy Docker images so they are accessible to the Kubernetes cluster. Examples:
    docker load --input images/VxmlConnector.tar
    docker load --input images/Envoy-VxmlConnector.tar

    Best practice—instead of copying images to each node in the cluster, the common practice is to push the image to a repository, tagging it, and pulling from there.

  5. Customize the configuration. Define required and optional parameters in an application.yaml file to be loaded when the Connector starts. See Configuring Helm deployments. (Customization is an iterative process. You can define required parameters in the initial deployment, then tune the configuration with subsequent modifications.)
  6. Install the helm chart. The chart bootstraps a deployment on a Kubernetes cluster using the Helm package manager.

    This command deploys VoiceXML Connector on the Kubernetes cluster with the vxmlconnector release name, the vxmlcon namespace, and a custom yaml configuration. You can use any values for the namespace and release name:

    $ kubectl create namespace vxmlcon
    $ helm install vxmlconnector <helmchart path> -n vxmlcon -f application.yaml

    The next example pulls images from a repository, and you must replace <repo.com>, <path>, and <tag> with specific values. (You can specify the configuration in application.yaml instead of using command line arguments.)  If installing helm from locally stored images, omit <repo.com>.

    helm install vxmlconnector helm/vxmlconnector-x.y.z.tgz -n vxmlcon-f application.yaml --set images.service.image="repo.com/path/vxml-connector:tag" --set envoy.deployment.image="repo.com/path/envoy:tag" --set images.service.pullPolicy="IfNotPresent" --set envoy.deployment.pullPolicy="IfNotPresent"
  7. Install optional software at any time.

Uninstalling the chart

To uninstall and delete the vxmlconnector deployment:

$ helm uninstall vxmlconnector

The command removes all previously deployed components associated with the chart and deletes the release.

Upgrading the chart

In the future, you can load new updates into Docker and upgrade the deployment:

$ helm upgrade vxmlconnector -f application.yaml

The command replaces the previously deployed Connector with a new release, and re-applies your YAML customizations.

Installation FAQ

Q: How do I use the Envoy image? 

The default deployment deploys a container image for an Envoy service that fronts the installed service. As start requests arrive from application stubs, the Envoy serivce balances load across VoiceXML Connector pods. If your deployment does not require balancing, you can disable Envoy.

Q: Can I run VoiceXML Connector in Docker without Kubernetes?

Running in a Docker-only mode is useful for small test systems. You can do this but it is not officially supported at this time. You need to translate the Helm configuration to the Docker configuration, and connect to the deployed Dialog service and Mix Artifact server.

Q: Must I install the Dialog service?

The Dialog service is required but you don't need to host it. You can connect to the Nuance-hosted service.

Q: Do I need Prometheus, Grafana, and Jaeger

These are the supported tools to gain insight into the service instances and their health. You can substitute tools that use the same data formats. For example, many tools accept these formats as de facto standards.

Updating third-party libraries

The VoiceXML Connector image has dynamic links to third-party libraries. You can update the following libraries at any time. For example, if a security flaw is detected in the current version.

  • com.io7m.xom:xom
  • com.google.code.findbugs:jsr305

Note: After an update, you must re-deploy the new image.

Update the base Docker image, and add the new library folder to CLASSPATH. Here is a Dockerfile script:

# replace <vxmlcon> with base image from your repository. Optionally, replace <latest> with any tag
FROM vxmlcon:latest

# replace <updated-lib-jar> with the new library and replace <provided-lib> with any folder name
ADD updated-lib-jar ${CATALINA_HOME}/lib/provided-lib

# add the new path to your setenv script for future persistence
RUN echo "export CLASSPATH=${CATALINA_HOME}/lib/provided-lib/*" >> ${CATALINA_HOME}/bin/setenv.sh

# set a command to execute the Tomcat startup script when the image runs
CMD ["/usr/local/tomcat/bin/catalina.sh", "run"]

# optional, set the working directory for any logon inside the container
WORKDIR $CATALINA_HOME

Next steps

For configuration details, see Configuring Helm deployments.

For instructions on running Mix dialog models from IVR applications, see Invoking VXML Connector from applications.