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 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:
(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
- Install the prerequisite and recommended software (listed above) in any order. Download the product package from Nuance Network and extract it.
- From the Cloud folder, extract VxmlConnector-x.y.z.tar.gz (where x.y.z is the version). Contents:
File Description 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
- 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.
- 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.)
- 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, thevxmlcon
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"
- 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.