Helm Charts

The Helm chart allows you to deploy the Ontotext Platform in Kubernetes with data provisioning, security, and monitoring.

If you do not have access to Ontotext’s Helm repository, please contact us at sales@ontotext.com to obtain the charts.

Prerequisites

Getting Started

If this is your first time installing a Helm chart, make sure to read the following introductions before continuing:

Binaries

Note

sudo may be required.

Kubernetes Environment

Minikube

Follow the install documentation for Minikube.

Driver

Carefully choose the suitable Minikube driver for your system.

Warning

Some of the drivers are compatible but have known issues. For example, the docker driver does not support the ingress add-on that is required, and the none driver goes into DNS resolve loop in some Linux distributions.

Resources

It is important to define resource limitations for the Minikube environment. Otherwise it will default to limits that may not be sufficient to deploy the whole Platform.

The default resource limitations require around 12 gigabytes of RAM. This is configurable per service in the values.yaml file and should be tuned for every deployment.

When starting Minikube, it is preferable to allocate a bit more than the required amount. For example, to create a Minikube environment in VirtualBox with 8 CPUs and 16 gigabytes of memory, use:

minikube start --vm-driver=virtualbox --cpus=8 --memory=16000

Add-ons

Minikube has built-in services as part of its add-on system. By default, some of the required plugins are disabled and have to be enabled.

To expose services, enable Minikube’s ingress with:

minikube addons enable ingress

To collect metrics, enable Minikube’s metrics server with:

minikube addons enable metrics-server

DNS Resolving

The Platform is deployed with a Kubernetes ingress service that is configured to listen for requests on a specific hostname. Any other requests are not handled.

This hostname is specified in values.yaml under deployment.host. By default, it is configured for localhost which is suitable for the none Minikube driver. In every other case, you need to reconfigure it to a hostname that is DNS resolvable.

Some of the options are:

  • Configure or update an existing DNS server - recommended for production deployment

  • Update your hosts file - suitable for local development

To find out the IP address of the Minikube environment, use:

minikube ip

If you wish to access the Platform locally on http://platform.local/ and the IP address of the Minikube environment is 192.168.99.102, you should modify your hosts file with:

192.168.99.102  platform.local

See this how-to on modifying the hosts file in different OS.

Secrets

  1. Create a secret for Ontotext Platform’s license.

Ontotext Platform requires a license in order to operate, which will be provided to you by our sales team. After obtaining a license, create a secret with a platform.license data entry:

kubectl create secret generic platform-license --from-file platform.license
  1. Create a secret for GraphDB’s license.

Ontotext Platform uses GraphDB to query and store Semantic Objects. It is a required component that requires a license. After obtaining one from our sales team, create a secret with a graphdb.license data entry:

kubectl create secret generic graphdb-license --from-file graphdb.license
  1. (Optional) Create a secret for pulling Docker images.

All Platform-related Docker images are published in DockerHub by default. This is required only if you will be pulling images from a secured Docker registry.

kubectl create secret docker-registry $DOCKER_REGISTRY \
        --docker-server=$DOCKER_REGISTRY_SERVER \
        --docker-username=$DOCKER_USER \
        --docker-password=$DOCKER_PASSWORD \
        --docker-email=$DOCKER_EMAIL

Replace the variables with the given credentials or export them in your environment before running the command. Then define or update the deployment.imagePullSecret value from the values.yaml file.

Note

Secret names can differ from the given samples but their configurations should be updated to refer to the correct ones. See values.yaml.

Quick Start

The Helm chart includes an example SOML schema and example security configurations. You can install the Platform with them.

However, they are only samples and it is not recommended to start and use them in a production deployment. See Customizing on how to override them.

To install the Platform on http://platform.local:

helm install --set deployment.host=platform.local ontotext-platform .

After a few seconds, Helm will print out the result from installing the Platform and the URLs that can be accessed.

You should see the following output:

--------------------------------------------------------------------------------------------
  ___        _        _            _         ____  _       _    __
 / _ \ _ __ | |_ ___ | |_ _____  _| |_      |  _ \| | __ _| |_ / _| ___  _ __ _ __ ___
| | | | '_ \| __/ _ \| __/ _ \ \/ / __|     | |_) | |/ _` | __| |_ / _ \| '__| '_ ` _ \
| |_| | | | | || (_) | ||  __/>  <| |_      |  __/| | (_| | |_|  _| (_) | |  | | | | | |
 \___/|_| |_|\__\___/ \__\___/_/\_\\__|     |_|   |_|\__,_|\__|_|  \___/|_|  |_| |_| |_|

--------------------------------------------------------------------------------------------
version: 3.4.0 | security: true | monitoring: true | federation: false
GDB cluster: false

** Please be patient while the chart is being deployed and services are available **
You can check their status with kubectl get pods

Endpoints:
* OTP workbench: http://platform.local/workbench
* GraphQL endpoint: http://platform.local/graphql
* GraphDB workbench: http://platform.local/graphdb
* FusionAuth: http://platform.local/admin
* Grafana: http://platform.local/grafana

You can also test the deployment by running:

helm test ontotext-platform

This runs special Kubernetes jobs that verify if services are accessible. See the Helm chart tests documentation.

Provisioning

The Kubernetes configurations are agnostic to data provisioning.

Initial provisioning of the SOML schema, and of the GraphDB repository & security configurations is realized with a Kubernetes Job. See templates/provision/platform-provision-job.yaml.

This separation achieves separation of data and infrastructure provisioning.

Once run, the data provisioning will not execute again.

Note

The first install of the Platform will be slow, because the hooks have to finish before Helm completes the install phase.

Persistence

By default, the Helm chart is deploying persistent volumes that store data on the host path. This is useful for local Minikube deployments. However, in a cloud environment with a multiple node cluster, this would lead to rescheduling and data loss.

For more details, see the Kubernetes Volumes documentation.

Local Deployment

Local persistent volumes are configured with deployment.storage from the values.yaml file.

Cloud Deployment

For cloud deployment, you have to prepare persistent disks, a storage class (or classes), and finally persistent volumes manifests. Once this is done, every component must be reconfigured in values.yaml to point to the new persistent volume and not the default one. Each component has a persistence section that has to be updated.

API Gateway

The Platform services are proxied using the Kong API Gateway. By default, it is configured to route:

  • Semantic Objects Service

  • GraphDB Workbench: configurable with platform.graphdb.expose from values.yaml

  • FusionAuth (if security is enabled)

  • Grafana (if monitoring is enabled): configurable with monitoring.grafana.expose from values.yaml

See the Kong default declarative configuration files/kong.dbless.yaml to understand what and how is proxied.

To learn more about the declarative syntax, see the Kong documentation.

Customizing

Every component is configured with sensible defaults, some of which are applied from the values.yaml file. Make sure to read it thoroughly, understand each property and the impact of changing any one of them.

The properties are used across configuration maps and secrets. Most of the components allow the overriding of their configuration maps and secrets from values.yaml.

See <component>.configmap and <component>.secret.

Note

If you are familiar with Kubernetes, you could modify the components configuration templates directly.

values.yaml

Helm allows you to override values from values.yaml in several ways.

  • Preparing another values.yaml:

helm install -f overrides.yaml ontotext-platform .
  • Overriding specific values:

helm install --set monitoring.enabled=false --set security.enabled=false ontotext-platform .

See the values files documentation for more information.

Deployment

Some of the important properties to update according to your deployment are:

  • deployment.protocol and deployment.host: configure the ingress controller and some of components on which they are accessible. The deployment.host must be a resolvable hostname and not an IP address.

  • deployment.storage: configures components where to store their persistent data on the host system running the Kubernetes environment.

Resources

Each component is defined with default resource limits that are sufficient to deploy the Platform and use it with small sets of data. However, for production deployments it is obligatory to revise these resource limits and tune them for your environment. You should consider common requirements like amount of data, users, or expected traffic.

Look for <component>.resources blocks in values.yaml. During Helm’s template rendering, these YAML blocks are inserted in the Kubernetes pod configurations as pod resource limits. Most resource configuration blocks are referring to official documentations.

See the Kubernetes documentation about defining resource limits.

Node Selectors

Each component in the Helm chart supports the specifying of a nodeSelector field in values.yaml. This allows to schedule pods across a multi-node cluster with different roles and resources. By default, no node restrictions are applied.

For more details, see the Kubernetes Assigning Pods to Nodes documentation.

GraphDB Repository

By default, the provisioning creates a default repository in GraphDB. This repo is provided by graphdb-repo-default-configmap that reads it from the examples/graphdb.default.ttl file.

To change the default TTL, you can prepare another configuration map containing a config.ttl file entry:

kubectl create configmap graphdb-repo-configmap --from-file=config.ttl

After that, update the property platform.graphdb.repositoryConfigmap from values.yaml to refer to the new configuration map.

GraphDB Cluster Mode

The Helm chart allows you to deploy GraphDB in cluster mode. By default, this is disabled and only a single master node is deployed.

To deploy in a cluster, enable platform.graphdb.cluster.enabled in the values.yaml file and configure platform.graphdb.cluster.workers.replicas to the desired replica amount. The platform.graphdb.cluster.workers configurations are similar to those of the master node.

See the GraphDB documentation on Setting up cluster with a single master.

SOML Schema

By default, the provisioning uses an example SOML schema. It is loaded from semantic-objects-soml-default-configmap that reads it from the examples/schema.default.yaml file.

You can change it by preparing another schema and creating a configuration map with it. The config map should contain a schema.yaml file entry:

kubectl create configmap soaas-soml-configmap --from-file=schema.yaml

After that, change the property platform.soaas.soml.configmap from values.yaml to point to the new configuration map.

API Gateway

By default, the Platform exposes most of the services. If you wish to update it, simply prepare another configuration map with Kong’s declarative syntax and update the platform.kong.configmap property.

Note

The configuration map should include a kong.yaml file entry.

Security

Security is enabled by default, and is provisioned by the opctl CLI tool.

This can be changed with the security.enabled boolean property. By turning it off, Helm will not deploy the security components (FusionAuth), will not provision GraphDB security, and Kong will not expect any JWT tokens.

By default, the provisioning uses an example from examples/opctl.default.yaml. It contains example users, JWT settings, FusionAuth tenant, and application settings, as well as GraphDB security configurations.

To change it, prepare another opctl configuration YAML and create a new secret containing an opctl.yaml file entry:

kubectl create secret generic opctl-config-secret --from-file opctl.yaml

Then, change the property platform.opctl.secret from values.yaml to point to the newly configured secret.

Note

Make sure to update the properties from values.yaml where credentials from opctl are mentioned (i.e., GraphDB).

Note

See the Platform CLI documentation for available opctl CLI configurations.

Apollo Federation Gateway

The Platform Helm chart allows you to include another /graphql endpoint and federate it under the Apollo federation gateway.

By default, the Apollo gateway is disabled and no federation is applied behind the /graphql endpoint. To change that, set platform.apollo.enabled to true and supply another configuration map that configures Apollo to federate all required /graphql endpoints. Then update the platform.apollo.services property to include the new configuration map.

By enabling Apollo, the API gateway will configure a /federation route through Apollo gateway.

Tip

The configurations under examples/federation/ provide more information on how to deploy custom services and configure the Apollo Gateway to federate them.

Note

See the GraphQL Federation documentation for Apollo configurations.

Monitoring

Monitoring is enabled by default. This can be changed by setting monitoring.enabled to false. By turning it off, Helm will not deploy any of the monitoring configurations and components.

Grafana notifications

By default, there are two prepared notifiers in the Platform’s Grafana image: e-mail and Slack.

After deploying the Platform, finish their configurations:

  • For Slack, you need to configure hook and recipient.

  • For e-mail, you need to configure addresses.

See the Monitoring documentation for more information.

Grafana SMTP

Grafana’s SMTP can be configured with the monitoring.grafana.smtp configurations from values.yaml. The SMTP is disabled by default.

Uninstall

To remove the deployed Platform, use:

helm uninstall ontotext-platform

Note

It is important to note that this will not remove any data, so the next time the Platform is installed, the data will be loaded by its components.

Provisioning will be skipped.

Troubleshooting

Helm Install Hangs

If there is no output after helm install, it is likely that a hook cannot execute. Check the logs with kubectl logs.

Connection Issues

If connections time out or the pods cannot resolve each other, it is likely that the Kubernetes DNS is broken. This is a common issue with Minikube between system restarts or when inappropriate Minikube driver is used. See the Kubernetes documentation for debugging DNS resolution information.