Helm Charts¶

Helm Chart Download¶

You can download the Ontotext Semantic Services Helm chart, including all sub-charts managed by Ontotext, from the Helm repository.

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

To add Ontotext’s Helm repository to your setup, execute:

helm repo add ontotext http://maven.ontotext.com/repository/helm-public/

See more information on how to use the external sub-charts:

• GraphDB Helm chart
• PostgreSQL HA Helm chart
• Grafana Helm chart
• InfluxDB Helm chart
• Elasticsearch Helm chart
• Kibana Helm chart

Local Deployment¶

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

• Docker
• Kubernetes concepts
• Minikube
• Helm

Binaries¶

• Install Helm.
• Install kubectl.
• Install Minikube.

Kubernetes Environment¶

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

minikube addons enable ingress

minikube addons enable metrics-server

minikube ip

192.168.99.102  platform.local

Secrets¶

First, you need to create some secrets with the Ontotext Semantic Services and GraphDB licenses that will be used by the Helm chart later.

1. Create a secret for the Semantic Services license.

   The Semantic Services require a license in order to operate, which will be provided to you by our sales team. After obtaining it, create a secret with the platform.license parameter:

   kubectl create secret generic platform-license --from-file platform.license
   

2. Create a secret for the GraphDB license.

   The Semantic Services use GraphDB to query and store Semantic Objects. It is a mandatory component that requires a license. After obtaining one from our sales team, create a secret with the graphdb.license parameter:

   kubectl create secret generic graphdb-license --from-file graphdb.license
   

3. (Optional) Create a secret for pulling Docker images.

   All Semantic Services-related Docker images are published in Docker Hub 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 global.imagePullSecrets map in 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.

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 ontotext/ontotext-platform
  

• Overriding specific values:

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

For more information, see the Helm values files documentation.

Deployment¶

Some of the important properties to update according to your deployment are: ingress.tls.*, graphdb.graphdb.protocol, and global.ingressHost. Configure the Ingress controller and some of components on which they are accessible. The global.ingressHost must be a resolvable hostname and not an IP address.

Resources¶

Each component is defined with default resource limits that are sufficient to deploy the Semantic Services and use them 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 on defining resource limits.

Assigning Pods to Nodes¶

Each component in the Helm chart supports specifying nodeSelector, affinity, and tolerations in values.yaml. This allows you to schedule pods across a multi-node cluster with different roles and resources.

Additionally, most components also support topologySpreadConstraints, which can be used to spread pods across failure domains in the cluster.

By default, no node restrictions are applied.

For more details, see the Kubernetes Assigning Pods to Nodes, Taints and Tolerations, and Pod Topology Spread Constraints documentation pages.

GraphDB Configuration¶

The Helm chart uses GraphDB’s Helm chart as a sub-chart and allows the usage of all options provided by the sub-chart. This includes:

• Different cluster topologies
• Security and properties provisioning
• Automated backups
• Repository consistency scans
• Extended master/worker nodes configurations

GraphDB Repository¶

By default, the provisioning creates a default repository in GraphDB. This repo is provided by graphdb-master-repo-configmap or graphdb-worker-repo-configmap (depending on whether or not a cluster is used) that reads it from the examples/graphdb/master.default.ttl or examples/graphdb/worker.default.ttl file.

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

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

After that, update the property graphdb.graphdb.masters.repositoryConfigmap graphdb.graphdb.workers.repositoryConfigmap from values.yaml to refer to the new configuration maps.

GraphDB Cluster Mode¶

The GraphDB 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 graphdb.graphdb.topology in the values.yaml file to 1m_3w/2m3w_rw_ro/2m3w_muted and configure graphdb.graphdb.clusterConfig to match the desired topology.

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

Search Service¶

The Ontotext Semantic Services Helm chart allows you to deploy the Ontotext Search Service as a sub-chart. The Search Service needs Elasticsearch and Kibana Helm charts in order to work properly. Those are added in Chart.yaml as dependencies.

To enable the deployment of the Search Service, search.enabled must be set to true in the values.yaml file. A few sub-sections in the values.yaml for platform-search, elasticsearch, and kibana must be filled as well.

When the Search Service is enabled and the Helm chart is deployed, the SOML schema will be provisioned to the Search Service as well as the Semantic Objects.

By default, the Search Service is enabled (see the values.yaml for details).

SOML and RBAC Schema¶

By default, the provisioning uses an example SOML schema and an RBAC schema. Both are loaded from templates/platform/platform-soml-schemas-configmap.yaml that reads the schemas from files/soml/schema.yaml and files/soml/rbac-schema.yaml files.

You can change the schemas by preparing another configuration map with the desired schema(s) inside. For example, if you want to override the SOML schema, the config map should contain a schema.yaml file entry:

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

After that, edit the semantic-objects.soml.schema.configmap property from values.yaml to point to the new configuration map.

The same applies for the RBAC schema. The property for it is semantic-objects.soml.rbac.configmap.

Security¶

Security is enabled by default and can be turned on and off with the security.enabled boolean property. However, due to some sub-chart configuration limitations, the deployment of FusionAuth and its database (PostgreSQL) must be turned off separately with the fusionauth.enabled and fusionauth_postgresql.enabled properties.

By default, the provisioning uses FusionAuth’s Kickstart with configuration files from files/fusionauth/*. It contains example users, JWT settings, FusionAuth tenant, and application settings.

To change the default users/roles or other provisioning settings, see the properties under security.*, such as security.roles and security.users.

PostgreSQL (used by FusionAuth) is deployed in HA mode with Pgpool. By default, only one replica is deployed, but this can be changed in the values.yaml file.

GraphDB Security¶

GraphDB can be secured separately without enabling the whole security stack. If security.enabled is false and graphdb.graphdb.security.enabled is true (the default), then the security provisioning will secure GraphDB automatically. By default, only basic security will be enabled. This is done through the settings.js, where you can set users and roles. More security-related options can be configured by providing a graphdb.properties file.

For more information, see the GraphDB Helm chart and the GraphDB Security documentation.

Apollo Federation Gateway¶

The Semantic Services 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 apollo.enabled to true and supply another configuration map that configures Apollo to federate all required /graphql endpoints. Then update the apollo.services property to include the new configuration map.

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

The Helm chart provides some default configurations for the Apollo gateway located in templates/platform/platform-apollo-*.

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.

The Ontotext Semantic Services Helm chart deploys Grafana and InfluxDB using their official Helm charts as sub-charts.

Telegraf is deployed with a custom sub-chart managed by Ontotext.

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 an incompatible Minikube driver is used. See the Kubernetes documentation on debugging DNS resolution.