+ All Categories
Home > Documents > Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux...

Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux...

Date post: 27-Jun-2020
Category:
Upload: others
View: 20 times
Download: 0 times
Share this document with a friend
70
Altair Knowledge Hub™ 2.4.2 ENTERPRISE SERVER INSTALLATION GUIDE
Transcript
Page 1: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub™ 2.4.2 ENTERPRISE SERVER INSTALLATION GUIDE

Page 2: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Engineering, Inc. All Rights Reserved. / Nasdaq:ALTR / altair.com

TABLE OF CONTENTS

[1] Altair Knowledge Hub Enterprise Server Installation Guide ................................................................ 1

Components .................................................................................................................................................... 1 Knowledge Hub Enterprise Server Cluster Components .................................................................. 2 Logging ............................................................................................................................................. 3

Horizontal Scalability ....................................................................................................................................... 3 Scalability Per Component ................................................................................................................ 3 Benefits of Kubernetes...................................................................................................................... 4

[2] Pre-Installation Procedures .................................................................................................................... 6

Amazon Elastic Container Service for Kubernetes (EKS) ............................................................................... 6 Manual Setup with CloudFormation Templates ................................................................................ 6 Knowledge Hub Prerequisite Configuration for Amazon EKS ........................................................... 6

Requirements: ............................................................................................................................. 6 Configuring Helm on the Cluster ................................................................................................. 6 Configuring External Ingress ....................................................................................................... 7 Configuring EFS Provisioner ....................................................................................................... 8 Configuring External DNS ........................................................................................................... 8 Configuring Internal Ingress ........................................................................................................ 9 Configuring the Kubernetes Dashboard .................................................................................... 10 Configuring ELK Charts ............................................................................................................. 11 Configuring NFS ........................................................................................................................ 12 Configuring Heapster................................................................................................................. 12 Configuring Monitoring .............................................................................................................. 13 Configuring Autoscaler .............................................................................................................. 14

On-Prem Cluster Using Kubespray ............................................................................................................... 15 Knowledge Hub Prerequisite Configuration for On-prem Kubespray .............................................. 16

Requirements: ........................................................................................................................... 16 Configuring Helm on the Cluster ............................................................................................... 16 Configuring External Ingress ..................................................................................................... 17 Configuring NFS ........................................................................................................................ 18 Configuring the Kubernetes Dashboard .................................................................................... 18 Configuring ELK Charts ............................................................................................................. 19 Configuring Heapster................................................................................................................. 20 Configuring Monitoring .............................................................................................................. 21

Google Compute Engine (GCE) .................................................................................................................... 22 Knowledge Hub Prerequisite Configuration for GCE ...................................................................... 22

Requirements ............................................................................................................................ 22 Configuring Helm on the Cluster ............................................................................................... 22 Configuring Nginx Ingress ......................................................................................................... 23 Configuring NFS ........................................................................................................................ 23 Configuring kubectl for GCE ...................................................................................................... 24

Page 3: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

[3] Knowledge Hub Helm Deployment ...................................................................................................... 25

Prerequisites ................................................................................................................................................. 25 Setting Up Knowledge Hub ........................................................................................................................... 25 Installing JDBC Drivers ................................................................................................................................. 28 OpenShift Deployment .................................................................................................................................. 28

Prerequisites ................................................................................................................................... 28 Setting Up Record Sets in AWS Route53 ..................................................................................................... 30 Setting Up the Core-API Properties File for File System Connections .......................................................... 30

[4] Spring Configuration ............................................................................................................................. 32

Core-API Properties ........................................................................................................................ 32 Data-Engine-API Properties ............................................................................................................ 34 License-API Properties ................................................................................................................... 37

[5] Security Protocols ................................................................................................................................. 38

Setting Up LDAP Authentication ................................................................................................................... 38 Setting Up Security Assertion Markup Language (SAML) Authentication ..................................................... 42

Configuring Okta IDP ...................................................................................................................... 42 Configuring SAML Properties in Core-API Properties ..................................................................... 46

Default Properties ...................................................................................................................... 48 Additional SAML Properties ....................................................................................................... 48

Running Helm Upgrade .................................................................................................................. 50 Advanced SAML Logging for Troubleshooting ................................................................................ 51 Other Optional Configurations ........................................................................................................ 51

Configuring Single Logout ......................................................................................................... 51 Configuring Assertion Encryption .............................................................................................. 52

Setting up OAuth2.0 Authentication .............................................................................................................. 52 Registering the Knowledge Hub Application to Azure Active Directory ........................................... 52 Configuring Core-API Properties .................................................................................................... 53

[6] Updating Knowledge Hub ..................................................................................................................... 55

Updating the Application ............................................................................................................................... 55 Updating the Licensing Type ......................................................................................................................... 55

From File Licensing to HWU Licensing ........................................................................................... 55 From HWU Licensing to File Licensing ........................................................................................... 56

Updating the Core-API Properties File for File System Connections ............................................................ 57

[7] Deleting Knowledge Hub Enterprise .................................................................................................... 59

Deleting Knowledge Hub Enterprise Server .................................................................................................. 59 Deleting Modules .......................................................................................................................................... 59

Deleting the Tracer (Jaeger) ........................................................................................................... 59

Page 4: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Deleting the Logger (ELK Stack) .................................................................................................... 59 Removing Monitoring (Grafana) ...................................................................................................... 60

Utilities Configuration .................................................................................................................................... 60

[8] Elastic Log Export/Import for Knowledge Hub Enterprise ................................................................. 61

Exporting Elasticsearch to AWS S3 .............................................................................................................. 61 Importing Logs in k8s ELK ............................................................................................................................ 62

[9] Migrating (Upgrading) Windows Installations to a Cluster ................................................................ 63

Backing Up/Restoring Knowledge Hub ......................................................................................................... 63 Backing Up Windows Installations .................................................................................................. 63 Backing Up Linux Enterprise Installations ....................................................................................... 63 Restoring Backed Up Installations via Kubernetes ......................................................................... 64

[10] Managing Cipher Keys ........................................................................................................................ 65

Creating Cipher Keys .................................................................................................................................... 65 Extracting Cipher keys .................................................................................................................................. 65 Updating Cipher keys .................................................................................................................................... 65 Migrating Cipher Keys from Windows to Enterprise Server Installations ....................................................... 66

Page 5: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 1

[1] ALTAIR KNOWLEDGE HUB ENTERPRISE SERVER INSTALLATION GUIDE

This document will guide you through the steps of installing Altair Knowledge Hub Enterprise Server.

WARNING

All code indicated in this document must be manually entered wherever necessary to avoid potential issues with missing/incorrect indentation, invisible characters, and the like. Copying and pasting code directly from this guide may result in failure to install, deploy, or update Knowledge Hub Enterprise Server.

Knowledge Hub is a highly scalable and flexible application. We strongly advise contacting your Altair account manager to obtain the recommended specifications for the deployment you wish to implement. Moreover, we recommend that all procedures to install and deploy Knowledge Hub Enterprise Server be completed by a knowledgeable system administrator.

COMPONENTS

Knowledge Hub Enterprise Server includes several components:

❑ The Knowledge Hub Enterprise Server application

❑ ELK Stack for logging

❑ Kubernetes Dashboard for system administration

These components are packaged in Helm Package Manager for Kubernetes with custom configurations.

Knowledge Hub Enterprise Server can be deployed to a private subnet for cloud deployments

❑ The Knowledge Hub web UI can be deployed to a public internet or private subnet

❑ The Kubernetes API/Dashboard is only accessible through bastion instances or VPN

Helm is used to install and update server and Knowledge Hub Enterprise application. Knowledge Hub Enterprise server is built on a Kubernetes cluster. You can use the command line tool kubectl to deploy and manage applications in Kubernetes.

Page 6: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 2

Knowledge Hub Enterprise Server Cluster Components

The following cluster components are included in Knowledge Hub Enterprise Server:

❑ license-api – Spring Boot 2 application

• Used as external licensing microservice

❑ ingress – Nginx controller for the Knowledge Hub Enterprise server application

• Ingress for Knowledge Hub clusters

• The only component that is visible to the outer world

• Used for TLS termination

❑ core http-api – Spring Boot 2 application

• Serves all Knowledge Hub core functionalities (HTTP and WebSocket endpoints)

• Swarm library (workspaces, data sources, connections, change lists, folders, etc.)

• User management (users, roles, groups)

• Process management (processes, schedules, etc.)

• Data readers/writers (CSV, excel, JDBC, etc.)

• Report trapping

• Data fetching and querying (design mode, batch mode, statistics)

❑ core api postgres – PostgreSQL server

• Used to store core api metadata objects

❑ data-engine http-api – Spring Boot 2 application

❑ data-engine api postgres – PostgreSQL server

• Used to store data-engine api metadata objects

❑ data-engine worker – Spring Boot 2 application

• Data Engine for design mode

❑ data-engine postgres  –  PostgreSQL server with PostgreSQL PL/Java

• Data engine backend used to store data sources data and query workspaces relational tree for design mode

❑ data-engine batch – Spring Boot 2 application and PostgreSQL server with PostgreSQL PL/Java

• Data Engine for batch requests

• Data engine backend used to store data sources data and query workspaces relational tree for export

❑ distributed cache – Redis server

• Used in the core http-api distributed mode as a hibernate l2 cache (metadata storage), spring cache (data source preview)

• Used in data-engine http-api distributed mode for distributed locks, maps, counters (data-engine).

❑ rabbitmq server − RabbitMQ message broker

• Used for asynchronous request for batch and design mode requests

Page 7: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 3

Logging ELK Stack is used to aggregate and visualize logs.

❑ Kibana is a tool for visualizing log data

❑ ElasticSearch is a search and analytics data engine

❑ Logstash is a data collector that obtains data from various sources, transforms them, and then sends them to some destination

To use Kibana, you must define the Knowledge Hub index pattern logstash-* manually. Steps to implement this

configuration are described in the documentation Defining Your Index Patterns. After configuring the Knowledge Hub index pattern, you can work with Knowledge Hub Enterprise Server logs on the Discover page.

By default, all logs (time and source) from the whole cluster (from all namespaces) from the last 15 minutes are displayed. You can filter logs by date or any available field to view them more conveniently and add other log information if you wish. You can view detailed information for all logs in Document data view.

HORIZONTAL SCALABILITY

Each component in the cluster can be scaled with known limitations.

Two types of scalability are supported:

❑ Manual scaling: driven by cluster/tenant administrator

❑ Automatic scaling: based on resource consumption (e.g., CPU) or specific metrics (e.g., request rate)

The scalability approach differs for stateful and stateless components:

❑ Stateful components (databases): Distributed cache, data-engine batch, rabbitmq-ha

❑ Stateless components (web apps): ingress, core http-api, core api postgres, data-engine http-api data-engine api postgres, data-engine worker, data-engine postgres

Spark is a unique component that already has some clustered solutions with the scalability approach:

❑ https://github.com/apache-spark-on-k8s/spark

❑ https://github.com/kubernetes/charts/tree/master/stable/spark

Scalability Per Component

❑ license-api — is not scalable by design

❑ ingress — Nginx is scalable by design

❑ core http-api — This component is stateless by design, so it can be scaled with some limitations

• core api postgres connections limit

• core api postgres throughput

❑ core api postgres — metadata storage for core http-api; this component is not scalable

❑ data-engine http-api — this component is stateless by design so can be scaled with some limitations:

• data-engine postgres connections limit

• data-engine postgres throughput

Page 8: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 4

❑ data-engine api postgres — metadata storage for data-engine http-api, this component is not scalable

❑ data-engine worker — data-engine for design-mode requests is stateless and scalable by design

❑ data-engine postgres — this component is not scalable by design

❑ data-engine batch — data-engine for batch process can be scaled

❑ rabbitmq-ha — message broker is scalable by design

❑ distributed cache — Redis is scalable by design

Additional Information

❑ https://kubernetes.io/docs/concepts/workloads/controllers/deployment/

❑ https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/

❑ https://wiki.postgresql.org/wiki/Replication,_Clustering,_and_Connection_Pooling

❑ https://redis.io/topics/cluster-spec

❑ https://www.nginx.com/blog/inside-nginx-how-we-designed-for-performance-scale/

Kubernetes deployments/statefulset with scaling support:

NAME TYPE SUPPORT SCALING

NOTES

license-api stateless false -

core-api stateless true –

core-api-postgres stateless false core-api database

data-engine-api stateless true Should be scaled on each node in the cluster

data-engine-api-postgres

stateless false data-engine-api database

data-engine-worker stateless true Should be scaled on each node in the cluster

data-engine-worker-batch

stateful true Should be scaled on each node in the cluster

rabbitmq-ha stateful true Should be scaled on each node in the cluster

depostgres stateless false Data engine for design mode, work with data-engine-worker.

redis stateful false Support leader-follower replication with persistence on file system

Benefits of Kubernetes

Kubernetes (k8s) is used as a cluster container orchestrator for:

❑ Automatic deployment

❑ Horizontal scaling

❑ Multitenancy (namespace-based)

❑ Storage orchestration

❑ Release management (helm-based)

❑ Self-healing

Page 9: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 5

❑ Service discovery and load balancing

❑ Secret and configuration management

Page 10: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 6

[2] PRE-INSTALLATION PROCEDURES

AMAZON ELASTIC CONTAINER SERVICE FOR KUBERNETES (EKS)

The following steps describe how to set up Amazon EKS Cluster and Knowledge Hub Enterprise with custom modules.

Manual Setup with CloudFormation Templates

❑ Use the link https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html to set up Amazon EKS.

❑ Set up Virtual Private Cloud (VPC) by using eks-vpc.yaml.

❑ Set up the Kubernetes worker nodes by using eks-nodes.yaml.

❑ Use the PrivateSubnets output from the first template as the Subnets parameter.

❑ Configure VPN. To set up a simple VPN server, use the eks-vpn.yaml CloudFormation template. The VPN

endpoint, username, and password are listed in CloudFormation Stack outputs.

Knowledge Hub Prerequisite Configuration for Amazon EKS

This section describes how to set up several modules from the Knowledge Hub Enterprise installer via Helm. Amazon EKS must be properly set up to configure these modules successfully.

Requirements:

❑ Kubernetes version 1.14

❑ Helm version 1.12.3 or 1.12

❑ Configured kubectl for Amazon EKS cluster

Configuring Helm on the Cluster

Home URL: https://github.com/helm/helm/releases/tag/v2.12.3

Commands:

kubectl apply -f tiller.yaml

helm init --service-account tiller --upgrade –wait

Page 11: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 7

tiller.yaml

---

apiVersion: v1

kind: ServiceAccount

metadata:

name: tiller

namespace: kube-system

---

apiVersion: rbac.authorization.k8s.io/v1

kind: ClusterRoleBinding

metadata:

name: tiller-clusterrolebinding

subjects:

- kind: ServiceAccount

name: tiller

namespace: kube-system

roleRef:

kind: ClusterRole

name: cluster-admin

apiGroup: ''

Configuring External Ingress

REQUIRED

Home URL: https://github.com/helm/charts/tree/master/stable/nginx-ingress

Command:

helm upgrade --install --namespace kube-system --values

nginx_ingress_values.yaml --version 1.0.1 --wait --timeout 600 lb

stable/nginx-ingress

nginx_ingress_values.yaml

nameOverride: lb

controller:

config:

proxy-body-size: 2048m

publishService:

enabled: true

service:

annotations:

service.beta.kubernetes.io/aws-load-balancer-backend-protocol:

tcp

service.beta.kubernetes.io/aws-load-balancer-connection-idle-

timeout: '1800'

service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-

balancing-enabled: 'true'

service.beta.kubernetes.io/aws-load-balancer-ssl-ports: https

targetPorts:

Page 12: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 8

http: http

https: https

type: LoadBalancer

load_balancer_type: aws-single

Configuring EFS Provisioner

REQUIRED

Home URL: https://github.com/helm/charts/tree/master/stable/efs-provisioner.

Create EFS and configure mount targets for cluster VPC and subnets by referring to the links https://docs.aws.amazon.com/efs/latest/ug/gs-step-two-create-efs-resources.html and https://docs.aws.amazon.com/efs/latest/ug/accessing-fs.html.

Command:

helm upgrade --install --namespace kube-system –values

efs_provisioner_values.yaml –version 0.1.1 --wait --timeout 600 efs-

provisioner stable/efs-provisioner

efs_provisioner_values.yaml

global:

deployEnv: prod

image:

tag: v1.0.0-k8s1.10

efsProvisioner:

efsFileSystemId: <efs_fsid>

awsRegion: <efs_aws_region>

path: /

storageClass:

name: default-nfs

isDefault: false

reclaimPolicy: Retain

Configuring External DNS

REQUIRED if Route53 Hosted Zone is used

Home URL: https://github.com/helm/charts/tree/master/stable/external-dns

Command:

helm upgrade --install --namespace kube-system --values

external_dns_values.yaml --version 0.7.6 --wait --timeout 600 external-dns

stable/external-dns

Page 13: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 9

external_dns_values.yaml

domainFilters: []

nameOverride: external-dns

policy: upsert-only

provider: aws

publishInternalServices: true

rbac:

create: true

sources:

- ingress

Configuring Internal Ingress

REQUIRED if Optional modules are used

Home URL: https://github.com/helm/charts/tree/master/stable/nginx-ingress

Command:

helm upgrade --install --namespace kube-system –values

internal_ingress_values.yaml --version 1.0.1 --wait --timeout 600 lb-internal

stable/nginx-ingress

internal_ingress_values.yaml

controller:

ingressClass: internal

config:

proxy-body-size: 2048m

publishService:

enabled: true

service:

annotations:

service.beta.kubernetes.io/aws-load-balancer-

internal: 0.0.0.0/0

service.beta.kubernetes.io/aws-load-balancer-backend-protocol:

tcp

service.beta.kubernetes.io/aws-load-balancer-connection-idle-

timeout: '1800'

service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-

balancing-enabled: 'true'

service.beta.kubernetes.io/aws-load-balancer-ssl-ports: https

targetPorts:

http: http

https: https

type: LoadBalancer

load_balancer_type: aws-single

nameOverride: lb

Page 14: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 10

Configuring the Kubernetes Dashboard

OPTIONAL

Home URL: https://github.com/helm/charts/tree/master/stable/kubernetes-dashboard

Steps:

1. Generate certificates for the domain or for dashboard URL only (tls.key, tls.crt) and then create a secret using these certificates:

kubectl create secret tls dashboard-tls-cert -n kube-system --

key tls.key --cert tls.crt

2. Generate auth password file:

htpasswd -bc ./auth <USERNAME> <PASSWORD>

3. Create Kubernetes secret:

kubectl create secret generic -n kube-system --from-file=./auth

ops-auth

Command:

helm upgrade --install --namespace kube-system -f dashboard_values.yaml --

force --wait dashboard stable/kubernetes-dashboard

dashboard_values.yaml

fullnameOverride: kubernetes-dashboard

image:

tag: v1.8.3

ingress:

annotations:

kubernetes.io/ingress.class: internal

nginx.ingress.kubernetes.io/auth-realm: Authentication Required!

nginx.ingress.kubernetes.io/auth-secret: ops-auth

nginx.ingress.kubernetes.io/auth-type: basic

nginx.ingress.kubernetes.io/backend-protocol: HTTPS

nginx.ingress.kubernetes.io/rewrite-target: /

enabled: true

hosts:

- <dashboard url>

path: /

tls:

- hosts:

- <dashboard url>

secretName: dashboard-tls-cert

Page 15: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 11

Configuring ELK Charts

OPTIONAL

Home URL: - (available in Knowledge Hub Enterprise archive)

Steps:

1. Create namespace for logging:

kubectl create ns logging

2. Generate certificates for domain or for Kibana URL only (tls.key, tls.crt) and create secret using these certificates:

kubectl create secret tls logs-tls-cert -n logging --key

tls.key --cert tls.crt

3. Generate auth password file:

htpasswd -bc ./auth <USERNAME> <PASSWORD>

4. Create Kubernetes secret:

kubectl create secret generic -n logging --from-file=./auth

ops-auth

Command:

helm upgrade --install --namespace logging -f logging_values.yaml --wait --

timeout 600 elk ./elk/elk-*.tgz

Define hostname <host> values in yaml file:

logging_values.yaml

elasticsearch:

data:

persistence:

size: 120Gi

kibana:

ingress:

annotations:

kubernetes.io/ingress.class: internal

kubernetes.io/tls-acme: "true"

nginx.ingress.kubernetes.io/auth-realm: Authentication

Required!

nginx.ingress.kubernetes.io/auth-secret: ops-auth

nginx.ingress.kubernetes.io/auth-type: basic

enabled: true

hosts:

- <host>

tls:

- hosts:

Page 16: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 12

- <host>

secretName: logs-tls-cert

Configuring NFS

OPTIONAL

Home URL: https://github.com/helm/charts/tree/master/stable/nfs-server-provisioner

Command:

helm upgrade --install --namespace kube-system --values nfs_values.yaml --

version 0.2.1 --wait --timeout 600 nfs stable/nfs-server-provisioner

nfs_values.yaml

nameOverride: nfs

persistence:

enabled: true

size: 150Gi

storageClass: ""

storageClass:

name: default-nfs

reclaimPolicy: Retain

Configuring Heapster

OPTIONAL

Home URL: https://github.com/helm/charts/tree/master/stable/heapster

Command:

helm upgrade --install --namespace kube-system -f heapster_values.yaml --

force –wait --timeout 600 heapster stable/heapster

heapster_values.yaml

image:

repository: k8s.gcr.io/heapster-amd64

tag: v1.5.3

rbac:

create: true

resizer:

enabled: false

Page 17: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 13

Configuring Monitoring

OPTIONAL

Home URL: (available in Knowledge Hub Enterprise archive)

Steps:

1. Create namespace for logging:

kubectl create ns monitoring

2. Generate certificates for domain or for Grafana URL only (tls.key, tls.crt) and then create secret using these certificates:

kubectl create secret tls logs-tls-cert -n monitoring --key

tls.key --cert tls.crt

3. Generate auth password file:

htpasswd -bc ./auth <USERNAME> <PASSWORD>

4. Create Kubernetes secret:

kubectl create secret generic -n monitoring --from-file=./auth

ops-auth

Command:

helm upgrade --install --namespace monitoring -f monitoring_values.yaml --

wait --timeout 600 monitoring ./monitoing/monitoring-*.tgz

Define hostname <host> values in yaml file:

monitoring_values.yaml

grafana:

env:

GF_SERVER_ROOT_URL: <host>

ingress:

annotations:

kubernetes.io/ingress.class: internal

kubernetes.io/tls-acme: "true"

nginx.ingress.kubernetes.io/auth-realm: Authentication

Required!

nginx.ingress.kubernetes.io/auth-secret: ops-auth

nginx.ingress.kubernetes.io/auth-type: basic

enabled: true

hosts:

- <host>

path: /

tls:

- hosts:

- <host>

secretName: monitoring-tls-cert

Page 18: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 14

Configuring Autoscaler

OPTIONAL

Home URL: https://github.com/helm/charts/tree/master/stable/cluster-autoscaler

Requirements: Configured and tagged ASG by instructions from Home URL

Command:

helm upgrade --install --namespace kube-system --values values.yaml --version

0.13.1 --wait --timeout 600 cluster-autoscaler stable/cluster-autoscaler

values.yaml

nameOverride: cluster-autoscaler

cloudProvider: aws

awsRegion: <aws region>

autoDiscovery:

clusterName: <eks cluster name>

sslCertPath: /etc/ssl/certs/ca-bundle.crt

extraArgs:

skip-nodes-with-system-pods: 'false'

skip-nodes-with-local-storage: 'false'

rbac:

create: create

pspEnabled: true

resources:

requests:

cpu: 0.1

memory: 300Mi

limits:

cpu: 0.3

memory: 600Mi

Page 19: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 15

ON-PREM CLUSTER USING KUBESPRAY

The following steps must be performed to prepare your on-prem cluster using Kubespray.

Steps:

1. Download the latest version of Kubespray from https://github.com/kubernetes-sigs/kubespray/releases.

2. Make sure that your system and Kubernetes cluster meet Kubespray requirements.

The following instructions are based on the Kubespray documentation: https://github.com/kubernetes-sigs/kubespray/blob/master/docs/getting-started.md

3. After downloading Kubespray, perform the following actions inside the Kubespray directory:

pip install -r requirements.txt

cp -r inventory/sample inventory/mycluster

4. Make the following changes:

• Change dashboard_enabled: true to dashboard_enabled: false in inventory/mycluster/group_vars/k8s-cluster/addons.yml. kubernetes-dashboard will be installed later using helm chart.

• Specify the kubernetes version in inventory/mycluster/group_vars/k8s-cluster/k8s-

cluster.yml via kube_version variable. A list of supported kubespray versions may be found in

roles/download/defaults/main.yml.

• Change other variables in inventory/mycluster/group_vars if needed. Documentation on these

variables may be found in https://github.com/kubernetes-sigs/kubespray/blob/master/docs/vars.md

• Configure the inventory/mycluster/host.ini file.

host.ini

[all]

## Configure 'ip' variable to bind kubernetes services

## on a different ip than the default iface set to 'ansible_host'

node1 ansible_host=<ip> etcd_member_name=etcd1 # ip=<private ip>

node2 ansible_host=<ip> etcd_member_name=etcd2 # ip=<private ip>

node3 ansible_host=<ip> etcd_member_name=etcd3 # ip=<private ip>

[kube-master]

node1

node2

node3

[etcd]

node1

node2

node3

[kube-node]

node1

node2

Page 20: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 16

node3

[k8s-cluster:children]

kube-master

kube-node

[all:vars]

kubeconfig_localhost=true

Additional instructions for modifying the host.ini file may be found at https://github.com/kubernetes-sigs/kubespray/blob/master/docs/ansible.md

5. Run Kubespray playbook:

ansible-playbook -i inventory/mycluster/hosts.ini cluster.yml -

b -v --private-key=<path to key> -u <remote user>

6. Configure kubectl

Accessing Kubernetes API

For public IP configuration, copy the file inventory/mycluster/artifacts/admin.conf to

~/.kube/config. Doing so will overwrite existing configuration.

Knowledge Hub Prerequisite Configuration for On-prem Kubespray

This section describes how to set up several modules from the Knowledge Hub Enterprise installer via helm. Kubespray must be properly set up to configure these modules successfully.

Requirements:

❑ Kubernetes version 1.14

❑ Helm version 1.12.3 or 1.12

❑ Configured kubectl for On-Prem cluster

Configuring Helm on the Cluster

Home URL: https://github.com/helm/helm/releases/tag/v2.12.3

Commands:

kubectl apply -f tiller.yaml

helm init --service-account tiller --upgrade –wait

tiller.yaml

---

apiVersion: v1

kind: ServiceAccount

Page 21: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 17

metadata:

name: tiller

namespace: kube-system

---

apiVersion: rbac.authorization.k8s.io/v1

kind: ClusterRoleBinding

metadata:

name: tiller-clusterrolebinding

subjects:

- kind: ServiceAccount

name: tiller

namespace: kube-system

roleRef:

kind: ClusterRole

name: cluster-admin

apiGroup: ''

Configuring External Ingress

REQUIRED

Home URL: https://github.com/helm/charts/tree/master/stable/nginx-ingress

Command:

helm upgrade --install --namespace kube-system --values

nginx_ingress_values.yaml --version 1.0.1 --wait --timeout 600 lb

stable/nginx-ingress

nginx_ingress_values.yaml

nameOverride: lb

controller:

kind: DaemonSet

hostNetwork: true

config:

proxy-body-size: 2048m

publishService:

enabled: true

service:

targetPorts:

http: http

https: https

type: ClusterIP

Page 22: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 18

Configuring NFS

REQUIRED

Home URL: https://github.com/helm/charts/tree/master/stable/nfs-server-provisioner

Command:

helm upgrade --install --namespace kube-system --values nfs_values.yaml --

version 0.2.1 --wait --timeout 600 nfs stable/nfs-server-provisioner

nfs_values.yaml

nameOverride: nfs

persistence:

enabled: true

size: 150Gi # adjust if needed

storageClass: ""

storageClass:

name: default-nfs

reclaimPolicy: Retain

Configuring the Kubernetes Dashboard

OPTIONAL

Home URL: https://github.com/helm/charts/tree/master/stable/kubernetes-dashboard

Steps:

1. Generate tls.key and tls.crt certificates for domain <host> (e.g.: dashboard-2.aws.dev-altair.com) and

upload them to the cluster:

kubectl create secret tls dashboard-tls-cert -n kube-system --

key tls.key --cert tls.crt

2. Generate auth password file:

htpasswd -bc ./auth <USERNAME> <PASSWORD>

3. Create Kubernetes secret:

kubectl create secret generic -n kube-system --from-file=./auth

ops-auth

Command:

helm upgrade --install --namespace kube-system -f dashboard_values.yaml --

force --wait dashboard stable/kubernetes-dashboard

Page 23: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 19

dashboard_values.yaml

fullnameOverride: kubernetes-dashboard

image:

tag: v1.8.3

ingress:

annotations:

kubernetes.io/ingress.class: nginx

nginx.ingress.kubernetes.io/auth-realm: Authentication Required!

nginx.ingress.kubernetes.io/auth-secret: ops-auth

nginx.ingress.kubernetes.io/auth-type: basic

nginx.ingress.kubernetes.io/backend-protocol: HTTPS

nginx.ingress.kubernetes.io/rewrite-target: /

enabled: true

hosts:

- <host>

path: /

tls:

- hosts:

- <host>

secretName: dashboard-tls-cert

Configuring ELK Charts

OPTIONAL

Home URL: Knowledge Hub Enterprise archive

Steps:

1. Create namespace for logging:

kubectl create ns logging

2. Generate certificates for hostname "<host>" tls.key and tls.crt and upload in the cluster:

kubectl create secret tls logs-tls-cert -n logging --key

tls.key --cert tls.crt

3. Generate auth password file:

htpasswd -bc ./auth <USERNAME> <PASSWORD>

4. Create Kubernetes secret:

kubectl create secret generic -n logging --from-file=./auth

ops-auth

Page 24: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 20

Command:

helm upgrade --install --namespace logging -f logging_values.yaml --wait --

timeout 600 elk ./helm/charts/elk-*.tgz

Define hostname <host> values in the yaml file, for example: logs-2.aws.dev-datawatch.com

logging_values.yaml

elasticsearch:

data:

persistence:

size: 120Gi # adjust if needed

kibana:

ingress:

annotations:

kubernetes.io/ingress.class: nginx

kubernetes.io/tls-acme: "true"

nginx.ingress.kubernetes.io/auth-realm: Authentication

Required!

nginx.ingress.kubernetes.io/auth-secret: ops-auth

nginx.ingress.kubernetes.io/auth-type: basic

enabled: true

hosts:

- <host>

tls:

- hosts:

- <host>

secretName: logs-tls-cert

Configuring Heapster

OPTIONAL

Home URL: https://github.com/helm/charts/tree/master/stable/heapster

Command:

helm upgrade --install --namespace kube-system -f heapster_values.yaml --

force –wait --timeout 600 heapster stable/heapster

heapster_values.yaml.

image:

repository: k8s.gcr.io/heapster-amd64

tag: v1.5.3

rbac:

create: true

resizer:

enabled: false

Page 25: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 21

Configuring Monitoring

OPTIONAL

Home URL: Knowledge Hub Enterprise archive

Steps:

1. Create namespace for logging:

kubectl create ns monitoring

2. Generate tls.key and tls.crt certificates for hostname "<host>" and upload to the cluster:

kubectl create secret tls logs-tls-cert -n monitoring --key

tls.key --cert tls.crt

3. Generate auth password file:

htpasswd -bc ./auth <USERNAME> <PASSWORD>

4. Create Kubernetes secret:

kubectl create secret generic -n monitoring --from-file=./auth

ops-auth

Command:

helm upgrade --install --namespace monitoring -f monitoring_values.yaml --

wait --timeout 600 monitoring ./helm/charts/monitoring-*.tgz

Define hostname <host>, for example: monitoring-2.aws.dev-altair.com, values in the yaml file

monitoring_values.yaml

grafana:

env:

GF_SERVER_ROOT_URL: https://<host>

ingress:

annotations:

kubernetes.io/ingress.class: nginx

kubernetes.io/tls-acme: "true"

nginx.ingress.kubernetes.io/auth-realm: Authentication

Required!

nginx.ingress.kubernetes.io/auth-secret: ops-auth

nginx.ingress.kubernetes.io/auth-type: basic

enabled: true

hosts:

- <host>

path: /

tls:

- hosts:

- <host>

secretName: monitoring-tls-cert

Page 26: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 22

GOOGLE COMPUTE ENGINE (GCE)

Knowledge Hub Prerequisite Configuration for GCE

To install and deploy Knowledge Hub on GCE, the latter must be correctly set up. Use the official documentation as a guide.

This section describes how to set up modules from the Knowledge Hub Enterprise installer.

Requirements

❑ Kubernetes version 1.14

❑ Helm version 1.12.3 or 1.12

❑ Configured kubectl for GCE

Configuring Helm on the Cluster

Home URL: https://github.com/helm/helm/releases/tag/v2.12.3

Commands:

kubectl apply -f tiller.yaml

helm init --service-account tiller --upgrade –wait

tiller.yaml

---

apiVersion: v1

kind: ServiceAccount

metadata:

name: tiller

namespace: kube-system

---

apiVersion: rbac.authorization.k8s.io/v1

kind: ClusterRoleBinding

metadata:

name: tiller-clusterrolebinding

subjects:

- kind: ServiceAccount

name: tiller

namespace: kube-system

roleRef:

kind: ClusterRole

name: cluster-admin

apiGroup: ''

Page 27: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 23

Configuring Nginx Ingress

REQUIRED

Home URL: https://github.com/helm/charts/tree/master/stable/nginx-ingress

Command:

helm upgrade --install --namespace kube-system --values

nginx_ingress_values.yaml --version 1.0.1 --wait --timeout 600 lb

stable/nginx-ingress

nginx_ingress_values.yaml

nameOverride: lb

controller:

config:

proxy-body-size: 2048m

publishService:

enabled: true

service:

type: LoadBalancer

To get EXTERNAL-IP, use the command:

kubectl get services lb-controller -n kube-system

and update hosts file with

<EXTERNAL-IP> <ingress_host from values.yaml>

Configuring NFS

OPTIONAL

Home URL: https://github.com/helm/charts/tree/master/stable/nfs-server-provisioner

Command:

helm upgrade --install --namespace kube-system --values nfs_values.yaml --

version 0.2.1 --wait --timeout 600 nfs stable/nfs-server-provisioner

nfs_values.yaml

nameOverride: nfs

persistence:

enabled: true

size: 150Gi

storageClass: ""

storageClass:

name: default-nfs

reclaimPolicy: Retain

Page 28: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 24

Configuring kubectl for GCE

Steps:

1. Install Google Cloud SDK https://cloud.google.com/sdk/docs/quickstart-debian-ubuntu.

2. Open https://console.cloud.google.com/home/dashboard in the browser and log in to your project.

3. Open the Linux console and run `gcloud auth login`.

4. Copy and open the output link in the browser.

5. Get the verification code and paste it in the console.

6. Get kubectl context using `gcloud container clusters get-credentials <cluster name> --zone <zone id> --project <project name>`.

7. Get nodes using `kubectl get nodes` to verify that the correct context is applied.

Page 29: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 25

[3] KNOWLEDGE HUB HELM DEPLOYMENT

Configure Kubernetes using any of the configurations detailed in the previous section. Then, configure and install modules from the Knowledge Hub prerequisites.

PREREQUISITES

Server:

❑ Kubernetes version 1.14

❑ Helm version 1.12.3 or 1.12

If you have an incompatible version of the client and helm server, please follow the documentation to upgrade tiller

❑ 2 ReadWriteMany persistence volumes or storage class with ReadWriteMany option (e.g.,: for Amazon EKS - EFS Provisioner, ... )

❑ 5+ ReadWriteOnce persistence volumes or storage class with ReadWriteOnce option (e.g.: for Amazon EKS - gp2 provisioner kubernetes.io/aws-ebs, ...)

❑ Large exports to S3/SMB/File System connections require Kubernetes nodes with a size of at least 200 GB

Client:

❑ Configured kubectl for cluster

❑ Helm version 1.12.3 or 1.12

❑ Windows or Linux OS terminal

Notes:

❑ Download the necessary libraries from the link provided to you by Altair. These libraries must be copied after Knowledge Hub installation to the folder \utils\libs.

❑ All commands are valid for Windows and Linux environments.

SETTING UP KNOWLEDGE HUB

The following instructions describe how to deploy Knowledge Hub Enterprise Server. In these steps, <knowledge

hub namespace> should be replaced with the Knowledge Hub Enterprise Server namespace.

Steps:

1. Download and unzip the installer archive.

2. Run /utils/utils.sh, select the 10th option to generate public and private keys for Knowledge Hub

Enterprise, and then update the Helm archive with these keys.

Page 30: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 26

3. Create a Knowledge Hub Enterprise namespace.

kubectl create ns <knowledge hub namespace>

4. Configure licensing.

Knowledge Hub supports two types of licensing:

• File licensing – Uses a license file provided by Altair. The license file contains a predefined number of users, data usage, and available features. Thus, the number of users that can be created and the number of rows that can be imported into the application are limited by the definitions provided in the license file.

• HyperWorks Units (HWU) licensing – Uses the Altair License Server based on HWUs to limit the number of users that can access the application simultaneously. In this case, each user “borrows” a certain number of units from the server when s/he starts working with Knowledge Hub and then releases these units when the session has been completed.

To configure the licensing type when Knowledge Hub is installed:

• If you are using File Licensing, deploy the Knowledge Hub Enterprise license in Kubernetes. Run the command from a folder with the license.lic file:

kubectl create secret generic -n <knowledge hub namespace>

license --from-file license.lic

The license secret must be created before running helm upgrade; otherwise, the core-api pod must be

restarted.

• If you are using HWU Licensing, update values.yaml file with the following property:

core-api:

config:

optionalEnv:

APPLICATION_LICENSE_PROVIDER: remote

license-api:

replicaCount: 1

config:

yaml:

application:

license:

provider: hwu

hwu:

host: "<license server port>@<license server host>"

# e.g. [email protected]

The file values.yaml must be updated before running helm upgrade; otherwise, the core-api pod must

be restarted.

5. Upload certificate for Knowledge Hub Enterprise domain:

kubectl create secret tls tls-cert -n <knowledge hub namespace>

--key tls.key --cert tls.crt

Page 31: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 27

You can generate a self-signed certificate, but doing so is not recommended for production use.

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout

tls.key -out tls.crt -subj "/CN=knowledgehub.local"

6. Configure values.yaml file. The /knowledgehub/example-values folder of build artifact contains

several sample files, each of which describes a different deployment size:

• aws-large-values.yaml

• aws-medium-values.yaml

• aws-small-values.yaml

Update the following properties in values.yaml:

• set &ingress_host to Knowledge Hub URL;

• set &registry to registry that will be used to pull images

• set &sharedStorageClass to storage class name of your cluster

7. To deploy Knowledge Hub Enterprise with custom values, select and edit <aws-values-yaml> configuration and execute:

helm upgrade --install --namespace <namespace> --timeout 900 -f

<values> -f <cipher_config> khub-24 <knowledgehub-*.tgz>

where:

• <namespace> is the created and configured (with license and CA secrets) Kubernetes namespace

• <aws-values-yaml> is one of:

aws-large-values.yaml

aws-medium-values.yaml

aws-small-values.yaml

• <values> is the path to the configured values.yaml file

• <cipher-config> is the path to the generated secrets file; usually in 'cipher/cipher_config.yaml'

• <knowledgehub-*.tgz> is the path to the Knowledge Hub chart archive; usually in 'knowledgehub/knowledgehub-*.tgz'

8. Upload the libraries to the server using the steps outlined here.

9. To check the installation, execute:

# to get chart status

helm ls -c knowledgehub

# to get statuses of all Knowledge Hub components

helm status knowledgehub

# to get chart values

helm get values knowledgehub

Page 32: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 28

INSTALLING JDBC DRIVERS

To create connections to third-party applications such as Google BigQuery, SQL Server, or to use Plugin Data Sources exported from Data Prep Studio, the appropriate drivers must be uploaded to Knowledge Hub Enterprise.

Steps:

1. Check that basic pack of drivers is present in the folder /utils/libs.

2. Run the script ./utils/utils.sh <KH kubernetes namespace> <KH helm release> and then choose option 3.

3. Restart the Knowledge Hub services by running the script ./utils/utils.sh <KH kubernetes

namespace> <KH helm release> and then choosing option 7.

4. Populate the setting APPLICATION_SERVER_INTERNET_ADDRESS in core-api.properties and data-engine-api.properties with the correct value.

Users seeking to create custom connections using other drivers (i.e., those not currently included in the set of drivers provided by Altair with installer) in Knowledge Hub should manually put the drivers' files to /utils/libs folder

and follow the steps above to do so. The JDBC versions of these drivers must be used.

OPENSHIFT DEPLOYMENT

Prerequisites

❑ Kubernetes version 1.14

❑ Kubectl client version v1.14 is installed

❑ Helm version 1.12.3 or 1.12

If you have an incompatible version of the helm client and server, upgrade tiller

Steps:

1. Install OpenShift CLI from https://github.com/openshift/origin/releases

2. Configure kubeconfig for OpenShift (copy openshift kubeconfig to ~/.kube/config).

3. Login to OpenShift using a user with permissions to create resources on OpenShift:

oc login -u <user> -p <password>

4. Configure helm by providing the tiller namespace:

export TILLER_NAMESPACE=<tiller namespace>

5. Create a new project in OpenShift for Knowledge Hub.

oc new-project <kh-project>

Page 33: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 29

6. Generate secret files using the utils.sh script with option 10.

7. Create license (if needed) and certificate secrets for KH:

kubectl create secret generic --namespace <kh-project> license

--from-file <license file> --dry-run --output yaml | kubectl

apply --force --filename -

kubectl create secret tls --namespace <kh-project> tls-cert --

key tls.key --cert tls.crt --dry-run --output yaml | kubectl

apply --force --filename -

8. Get the OpenShift UID range.

oc describe project <kh-project>

The range value will be in the annotation openshift.io/sa.scc.uid-range and will look like

1000530000/10000; you will need only 1000530000.

9. Replace changeMe in the openshift-restricted.yaml file with the UID from the command above.

10. Install Knowledge Hub using helm.

helm upgrade --install --namespace <kh-project> --timeout 900 -

-values openshift-values.yaml --values openshift-

restricted.yaml --values cipher_config.yaml <kh-helm>

knowledgehub-*.tgz

11. If Kerberos Password authentication and Anonymous access are required (e.g., for HDFS connection usage), the following steps must be executed before Step 9 above to call native libraries from which information about the Unix user will be obtained.

• Configure OpenShift security policies for Knowledge Hub:

oc adm policy add-scc-to-user nonroot

system:serviceaccount:<kh-project>:<kh-helm>-data-engine-api

oc adm policy add-scc-to-user nonroot

system:serviceaccount:<kh-project>:<kh-helm>-data-engine-worker

oc adm policy add-scc-to-user nonroot

system:serviceaccount:<kh-project>:<kh-helm>-data-engine-batch

• Install Knowledge Hub using helm:

helm upgrade --install --namespace <kh-project> --timeout 900 -

-values openshift-values.yaml --values openshift-

restricted.yaml --values openshift-krb5.yaml --values

cipher_config.yaml <kh-helm> knowledgehub-*.tgz

Ensure that libraries for Hive or Hadoop are not included to avoid conflicts during installation.

Page 34: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 30

SETTING UP RECORD SETS IN AWS ROUTE53

To enable access to the Knowledge Hub server via a public DNS, implement the following steps.

Steps:

1. Check the AWS load balancers created during installation and get the DNS name of a load balancer that does not include “internal” in its name and has listeners with ports 80 and 443.

2. Go to Route53 in AWS console and create two record sets:

• Create record set A record.

“Alias Target” is the DNS name of the load balancer.

• Create record set TXT record with the value "heritage=external-dns,external-

dns/owner=default,external-dns/resource=ingress/knowledgehub/

knowledgehub-core-api"

Note: /knowledhehub/ is the namespace

When these steps are completed, Knowledge Hub Enterprise Server will be accessible using the new URL.

SETTING UP THE CORE-API PROPERTIES FILE FOR FILE SYSTEM CONNECTIONS

In Knowledge Hub 2.4.1, system administrators must specify root (base) paths to file folders to which users can create connections in the configuration file before these connections can be made.

Steps:

1. After installing Knowledge Hub 2.4.1, stop all Knowledge Hub services.

2. Open the file core-api.properties and then add the following properties:

“APPLICATION_IO_CONNECTION_FILESYSTEM_ROOTPATHS_ROOT_PATH”:

“/var/swarm/file-library”

“APPLICATION_IO_CONNECTION_FILESYSTEM_ROOTPATHS_ROOT_PATH2”:

“/var/swarm/file-library2”

where:

/var/swarm/file-library – is the path to one directory

/var/swarm/file-library2 – is the path to another directory

IMPORTANT: Base paths are case-sensitive. When specifying a base path to use for file system connections, ensure that the case for all folder names, including the drive letter, are provided exactly as formatted.

Page 35: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 31

NOTES:

• All root paths must be unique.

• Multiple root paths can be specified by using the properties ROOT_PATH, ROOT_PATH2, ROOT_PATH3, etc.

• If multiple paths contain the same start path (e.g., path1: var/swarm/file library; path2: var/swarm/file library/reports), these paths are divided into a root path (i.e., var/swarm/file library) and an extended path (/reports). Connections to these two paths may then be created.

3. Restart all Knowledge Hub services.

Page 36: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 32

[4] SPRING CONFIGURATION

Note: Key properties should be in upper case and use '_' instead of '.' and '-' (e.g., spring.datasource.url

should be SPRING_DATASOURCE_URL; application.server.internet-address should be

APPLICATION_SERVER_INTERNET_ADDRESS.

Use optionalEnv to set properties:

core-api:

config:

optionalEnv:

CONFIGURATION_PROPERTY_KEY_1: "value"

CONFIGURATION_PROPERTY_KEY_2: "value"

data-engine-api:

config:

optionalEnv:

CONFIGURATION_PROPERTY_KEY_1: "value"

CONFIGURATION_PROPERTY_KEY_2: "value"

data-engine-batch:

worker:

config:

optionalEnv:

CONFIGURATION_PROPERTY_KEY_1: "value"

CONFIGURATION_PROPERTY_KEY_2: "value"

data-engine-worker:

config:

optionalEnv:

CONFIGURATION_PROPERTY_KEY_1: "value"

CONFIGURATION_PROPERTY_KEY_2: "value"

Core-API Properties

The following table describes, in detail, the parameters that may be added/modified for this service.

PARAMETER DESCRIPTION

SPRING

SPRING_DATASOURCE_URL

SPRING_DATASOURCE_USERNAME

SPRING_DATASOURCE_PASSWORD

Describes the connection to the Postgres database for the Knowledge Hub service

SPRING_HTTP_MULTIPART_MAXFILESIZE

SPRING_HTTP_MULTIPART_MAXREQUESTSIZE

Describes the maximum size of files that may be uploaded to the application (e.g., 2000MB)

SERVER

SERVER_PORT Port on which the application is running

SERVER_SSL_ENABLED

SERVER_SSL_KEY_STORE

SERVER_SSL_KEY_STORE_PASSWORD

SERVER_PORT_SSL_KEY_PASSWORD

Certificate settings for HTTPS

Page 37: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 33

PARAMETER DESCRIPTION

APPLICATION

APPLICATION_SERVER_INTERNET_ADDRESS Specifies the <protocol>://<server>:

<port> of the authorized redirect URL for login

to Salesforce, Google Analytics, Google Adwords, etc. The redirect URL should be identical to the URL specified for ClientId and ClientSecret for Google connections.

For example, if the authorized redirect Uri is https://bp-south.swarm.dev-

altair.com:8443/connections/

oauthRedirectUrl, the value

https://bp-south.dev-altair.com:

8443 should be specified for this property.

APPLICATION_HTTP_CACHE_TIMETOLIVEINDAYS Describes the amount of time in days that may elapse before a data source’s cache times out

APPLICATION_DATA_ENGINE_STORE_

DESIGN_MODE_LIMIT

Describes the row limit to be used for data sources in Design Mode; the default value is 10K

APPLICATION_DATA_ENGINE_STORE_

GLOBALROWLIMIT

Row limit applied when the Design Mode limit is disabled

e.g., 5000

APPLICATION_DATA_ENGINE_API_URL URL for internal communication between Knowledge Hub and Knowledge Hub Data Engine services (http://<machine name>:8081)

You can change the port on which the Data Engine will run by specifying a different port number for this property. The value you enter must match the value provided for the server_port property in the Data-Engine-API Properties file. Both services must be restarted when this property is updated.

APPLICATION_DSL_SOURCE_CLEANER_CRON

APPLICATION_DSL_SOURCE_EXPIRATION_

IN_HOURS

APPLICATION_DSL_TEMPORARY_ITEM_

CLEANER_CRON

APPLICATION_DSL_TEMPORARY_ITEM_

EXPIRATION_IN_HOURS

APPLICATION_DSL_PROCESS_RUN_CLEANER

_CRON

APPLICATION_DSL_PROCESS_RUN_

CLEANER_EXPIRATION_TIME

Describes settings for jobs that delete temporary objects

APPLICATION_LICENSE_LOCAL_FILEPATH Describes the path to the Knowledge Hub license

APPLICATION_IO_CONNECTION_DISABLED Specifies which connection types to disable (hide) in Knowledge Hub for all users

APPLICATION_IO_APPDATAFOLDER Describes the path to the application’s internal storage (i.e., File Library; default: /var/swarm/file-library/Datawatch/DNS/InternalStorage

APPLICATION_IO_CONNECTION_FILESYSTEM_

ROOTPATHS_ROOT_PATH

ROOT_PATH: /var/swarm/file-library

ROOT_PATH2: /var/swarm/file-library2

Specifies which file folders to expose when creating File System connections. If root paths are not specified in the config file, Knowledge Hub users will not be able to create File System connections because a base path is required for this type of connection.

Page 38: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 34

PARAMETER DESCRIPTION

APPLICATION_SECURITY_AUTHENTICATION_

XAUTH_TOKEN_VALIDITYINSECONDS

Describes how many seconds should elapse before a user times out

e.g., 1800

APPLICATION_SCHEDULES_MONITORING_

INTERVALINMINUTES

Number of minutes that must elapse before the next monitoring operation should be executed in a monitoring schedule

APPLICATION_SECURITY_AUTHENTICATION_

FAILED_ATTEMPT_MIN_DELAY_SEC

Delay after the first failed login attempt

e.g., 8

APPLICATION_SECURITY_AUTHENTICATION_

FAILED_ATTEMPT_MAX_DELAY_SEC

Maximum delay time after a failed login attempt, e.g., 600

Data-Engine-API Properties

The following table describes, in detail, the parameters that may be added/modified for this service.

PARAMETER DESCRIPTION

SPRING

SPRING_DATASOURCE_URL

SPRING_DATASOURCE_USERNAME

SPRING_DATASOURCE_PASSWORD

Describes the connection to the Postgres database for the Knowledge Hub service

LOGGING

LOGGING_FILE Full path to the Data Engine service log file

LOGBACK_LOGLEVEL Logging level of the Data Engine service log file

SERVER

SERVER_PORT 8081 – port on which the Data Engine is running

You can change the port on which the Data Engine will run by specifying a different port number for this property. The value you enter must match the value provided for the application_data_engine_ api_url property in the Core-API Properties file. Both services must be restarted when this property is updated.

SERVER_SSL_ENABLED

SERVER_SSL_KEY_STORE

SERVER_SSL_KEY_STORE_PASSWORD

SERVER_SSL_KEY_PASSWORD

Certificate settings for HTTPS

APPLICATION

APPLICATION_DATA_ENGINE_POSTGRES_

COPY_INTERFACE_ENABLED

Setting to specify which method to use (i.e., COPY or ResultSet) when loading data from Postgres during export so that the operation is completed faster.

true/false – if the value true is selected, the COPY interface is used. Otherwise, the ResultSet read method is used.

This setting should also be specified in data-engine-worker and data-engine-worker-batch properties.

Page 39: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 35

PARAMETER DESCRIPTION

APPLICATION_DATA_ENGINE_POSTGRES_

READER_BUFFER_SIZE

Specifies the buffer size to use when reading data from Postgres (e.g., 80 MB).

This setting should also be specified in data-engine-worker, and data-engine-worker-batch properties.

APPLICATION_DATA_ENGINE_STORE_

STATISTICS_AWAIT_TIMEOUT

Time to wait before statistics requests time out (e.g., 60s)

APPLICATION_DATA_ENGINE_STORE_

COLUMN_LIMIT

100 - column limit after Pivot and Transpose.

APPLICATION_DATA_ENGINE_STORE_

DISTINCT_VALUE_LIMIT

250 - number of displayed distinct values limit

APPLICATION_DATA_ENGINE_STORE_

LIMIT_DATA_NODES

Enables or disables limit to count of rows in all data nodes

e.g., true (enabled); false (disabled)

APPLICATION_DATA_ENGINE_STORE_

EXPORT_DATA_AWAIT_TIMEOUT_IN_SEC

3600 - export timeout

APPLICATION_SERVER_INTERNET_ADDRESS Specifies the <protocol>://<server>:

<port> of the authorized redirect URL for login to

Salesforce, Google Analytics, Google Adwords, etc. The redirect URL should be identical to the URL specified for ClientId and ClientSecret for Google connections.

For example, if the authorized redirect Uri is https://bp-south.swarm.dev-

altair.com:8443/connections/

oauthRedirectUrl, the value

https://bp-south.dev-altair.com:

8443 should be specified for this property.

APPLICATION_SECURITY_AUTHENTICATION_

XAUTH_SECRET

Security token, should be equal to all other security tokens in all other application config files

APPLICATION_CORE_API_URL Address for internal communication with the Knowledge Hub service

APPLICATION_IO_INTERNAL_STORAGE_

FOLDER

InternalStorage - Specifies the folder in which internal exports are stored.

By default, internal data source files are stored in /var/swarm/file-library/Datawatch/DNS/InternalStorage

This setting must also be specified in data-engine-worker and data-engine-worker-batch to function correctly.

WRITER

APPLICATION_IO_WRITER_COGNOS_

HTTP_CLIENT_TIMEOUT

600 - timeout for connection to IBM Cognos Analytics

READER

APPLICATION_IO_READER_PREVIEW_LIMIT 1000 – row limit for previewing data sources

JDBC SETTINGS

APPLICATION_IO_READER_JDBC_TIMEOUT_

IN_SEC

Describes the time in seconds that may elapse before connections to JDBC drivers time out

e.g., 60

APPLICATION_IO_READER_JDBC_FETCH_SIZE Describes the number of rows to fetch for a query to a database using JDBC drivers, e.g., 200

APPLICATION_IO_READER_JDBC_DRIVER_* Configuration settings for JDBC drivers

Page 40: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 36

PARAMETER DESCRIPTION

APPLICATION_IO_READER_JDBC_DRIVER_

DEFAULT_LOGINTIMEOUT

Describes the time in seconds that may elapse before connections to JDBC drivers time out after login

e.g., 60

APPLICATION_IO_READER_JDBC_DRIVER_

DEFAULT_SOCKETTIMEOUT

Describes the time in seconds that may elapse before a socket timeout occurs when using connections to JDBC drivers (e.g., 60)

APPLICATION_IO_READER_JDBC_DRIVER_

CDATA_JDBC_ALL_TIMEOUT

Describes the time in seconds that may elapse before all connections to JDBC drivers time out (e.g., 60)

APPLICATION_IO_READER_JDBC_DRIVER_

COM_MYSQL_JDBC_DRIVER_USECURSOR

FETCH

APPLICATION_IO_READER_JDBC_

DRIVER_COM_MYSQL_JDBC_DRIVER_

LOGINTIMEOUT

APPLICATION_IO_READER_JDBC_DRIVER_

COM_MYSQL_JDBC_DRIVER_SOCKETTIMEOUT

Settings for mySQL JDBC driver

APPLICATION_IO_READER_JDBC_DRIVER_

ORACLE_JDBC_ORACLEDRIVER_ORACLE_

NET_CONNECT_TIMEOUT

APPLICATION_IO_READER_JDBC_DRIVER_

ORACLE_JDBC_ORACLEDRIVER_ORACLE_

JDBC_READTIMEOUT

Settings for Oracle JDBC driver

APPLICATION_IO_READER_JDBC_DRIVER_

COM_FACEBOOK_PRESTO_JDBC_

PRESTODRIVER_SSL

APPLICATION_IO_READER_JDBC_DRIVER_

COM_FACEBOOK_PRESTO_JDBC_

PRESTODRIVER_PASSWORD

Settings for Presto JDBC driver

APPLICATION_IO_READER_JDBC_DRIVER_

ORG_APACHE_HIVE_JDBC_HIVEDRIVER_

JAVA_SECURITY_KRB5_CONF

APPLICATION_IO_READER_JDBC_DRIVER_

ORG_APACHE_HIVE_JDBC_HIVEDRIVER_

JAVA_SECURITY_AUTH_LOGIN_CONFIG

Settings for Apache Hive JDBC driver

REPORT TRAPPING

APPLICATION_TRAPPING_REPORT_

TEXT_VIEW_MAX_CACHE_IN_MB

This option sets the limit in megabytes for storing the converted reports.

APPLICATION_TRAPPING_REPORT_

TEXT_VIEW_MAX_CACHE_COUNT

This option sets the limit in counts for storing the converted reports.

APPLICATION_TRAPPING_REPORT_

TEXT_VIEW_NUMBER_OF_PAGES

If the page number of THE report exceeds this setting, then conversion option converts from PDF reports to TXT report

Page 41: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 37

License-API Properties

The following table describes, in detail, the parameters that may be added/modified for this service.

You can easily switch between license providers:

❑ local – license specified in APPLICATION_LICENSE_LOCAL_FILEPATH

❑ hwu – Local core-api HWU License Service provider.

PARAMETER DESCRIPTION

SPRING

SPRING_APPLICATION_NAME Name of Spring application (license-api)

SERVER

SERVER_PORT 8085 - Port on which License service is running

SERVER_SSL_ENABLED

SERVER_SSL_KEY_STORE

SERVER_SSL_KEY_STORE_PASSWORD

SERVER_SSL_KEY_PASSWORD

Certificate settings for HTTPS

SERVER_COMPRESSION_ENABLED Enable or disable HTTP response compression

SERVER_COMPRESSION_MIME_TYPES Content types that are compressed (e.g., text/html, application/json)

APPLICATION

APPLICATION_LICENSE_PROVIDER Type of license provider, can be “local” or “hwu”

APPLICATION_LICENSE_LOCAL_FILEPATH Path to license.lic file

APPLICATION_LICENSE_HWU_HOST Altair License Server address. Should be written as “<port>@<host>”. The URL to the Altair License Server should be set as an environment variable.

APPLICATION_LICENSE_HWU_CHECKER_CRON Schedule to execute remote license pool check (e.g., 00/5 * * * *)

APPLICATION_LICENSE_HWU_GROUP Name of group on Altair License Server (e.g., ${COMPUTERNAME}). This property should also be set as an environment variable.

APPLICATION_LICENSE_HWU_LOG_ENABLED Enable (true) or disable (false) hwu logging

APPLICATION_LICENSE_HWU_LOG_LEVEL Level of hwu logging (e.g., info)

APPLICATION_LICENSE_HWU_LOG_FACILITY Type of output (e.g., stderr)

Page 42: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 38

[5] SECURITY PROTOCOLS

The sections below describe how to set up different types of authentication on Knowledge Hub.

WARNING

All code indicated in this document must be manually entered wherever necessary to avoid potential issues with missing/incorrect indentation, invisible characters, and the like. Copying and pasting code directly from this guide may result in failure to install, deploy, or update Knowledge Hub Enterprise Server.

SETTING UP LDAP AUTHENTICATION

The following steps describe how to implement LDAP authentication in Knowledge Hub.

Steps:

1. Update <namespace>-core-api properties in ConfigMaps. You can do this by using running kubectl

edit cm <namespace>-core-api in a terminal connected to your cluster or using UI tools such as

Kubernetes Dashboard or Google Cloud Platform console.

{…

"data":{

"APPLICATION_SECURITY_AUTHENTICATION_PROVIDER": "ldap <available values:

basic, ldap, oauth2>",

"APPLICATION_SECURITY_AUTHENTICATION_USERSPROVISIONED": "false",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_ACTIVEDIRECTORY": "true",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_DOMAIN": "<domain>",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_SERVER": "ldap://<full computer

name of Knowledge Hub server>.<domain name>/",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_MANAGEDN": "<LDAP admin user>",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_MANAGEPASSWORD":

"<password of admin user>",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_ATTRIBUTEMAPPING_

COMMONNAME": "cn",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_ATTRIBUTEMAPPING_

EMAIL": "mail",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_ATTRIBUTEMAPPING_

FIRSTNAME": "givenname",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_ATTRIBUTEMAPPING_

GROUPS": "memberOf",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_ATTRIBUTEMAPPING_

LASTNAME": "sn",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_ATTRIBUTEMAPPING_

LOGIN": "userPrincipalName",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_ATTRIBUTEMAPPING_

PHONENUMBER": "telephonenumber",

Page 43: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 39

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_CUSTOMATTRIBUTES":

"displayName, distinguishedName, name, objectCategory, objectClass,

primaryGroupID, sAMAccountName, sAMAccountType,

servicePrincipalName",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_SEARCHBASE"= "DC: "<domain

component 1>,DC=<domain component 2>",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_SEARCHFILTER": "(|

(userPrincipalName={0}) (sAMAccountName={0}))",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_ROLEMAPPING": "true",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_ROLESMAP_1": "GroupName1,

GroupName2",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_ROLESMAP_2": "GroupName1,

GroupName2",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_USERROLES": "2",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_ADMINUSERS": "<admin user1>,

<admin user2>"

}

}

For example, if the full computer name of the Knowledge Hub server is WIN-SWARMSERVER, the LDAP server is WIN-LDAPSERVER, and the domain name is altair.com:

{…

"data":{

"APPLICATION_SECURITY_AUTHENTICATION_PROVIDER": "ldap",

"APPLICATION_SECURITY_AUTHENTICATION_USERSPROVISIONED": "false",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_ACTIVEDIRECTORY": "true",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_DOMAIN": "ALTAIR.COM",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_SERVER": "ldap://WIN-

LDAPSERVER.altair.com/",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_MANAGEDN":

"[email protected]>",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_MANAGEPASSWORD":

"#Passw0rd#",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_ATTRIBUTEMAPPING_

COMMONNAME": "cn",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_ATTRIBUTEMAPPING_

EMAIL": "mail",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_ATTRIBUTEMAPPING_

FIRSTNAME": "givenname",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_ATTRIBUTEMAPPING_

GROUPS": "memberOf",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_ATTRIBUTEMAPPING_

LASTNAME": "sn",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_ATTRIBUTEMAPPING_

LOGIN": "userPrincipalName",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_ATTRIBUTEMAPPING_

PHONENUMBER": "telephonenumber",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_QUERY_CUSTOMATTRIBUTES":

"displayName, distinguishedName, name, objectCategory, objectClass,

primaryGroupID, sAMAccountName, sAMAccountType,

servicePrincipalName",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_SEARCHBASE"= "DC=altair,DC=com",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_SEARCHFILTER": "(|

(userPrincipalName={0}) (sAMAccountName={0}))",

Page 44: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 40

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_ROLEMAPPING": "true",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_ROLESMAP_1": "Accounting,

Finance",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_ROLESMAP_2": "BusDev, Sales",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_USERROLES": "2",

"APPLICATION_SECURITY_AUTHENTICATION_LDAP_ADMINUSERS": "[email protected],

[email protected]"

}

}

Each of the properties that can added to core-api properties is described as follows:

PROPERTY DESCRIPTION

APPLICATION_SECURITY_AUTHENTICATION_

PROVIDER

Assigns the authentication type for the Knowledge Hub application

Possible values:

❑ ldap

❑ basic

❑ oauth2

APPLICATION_SECURITY_AUTHENTICATION_

USERS_PROVISIONED

Enables (true) or disables (false) explicit

provisioning.

If explicit provisioning is disabled, the system creates Knowledge Hub users automatically.

When set to true, users must be created

manually

APPLICATION_SECURITY_AUTHENTICATION_

DEFAULT_PASSWORD

The default password for new users created through LDAP and added multiple users

APPLICATION_SECURITY_AUTHENTICATION_

LDAP_QUERY_ATTRIBUTE_MAPPING_

LOGIN: USERPRINCIPALNAME

FIRST_NAME: GIVENNAME

LAST_NAME: SN

COMMON_NAME: CN

EMAIL: MAIL

PHONE_NUMBER: TELEPHONENUMBER

GROUPS: MEMBEROF

Attributes used to add users by LDAP query

APPLICATION_SECURITY_AUTHENTICATION_

LDAP_QUERY_CUSTOM_ATTRIBUTES

DISPLAYNAME

DISTINGUISHEDNAME

NAME

OBJECTCATEGORY

OBJECTCLASS

PRIMARYGROUPID

SAMACCOUNTNAME

SAMACCOUNTTYPE

SERVICEPRINCIPALNAME

APPLICATION_SECURITY_AUTHENTICATION_

LDAP_ACTIVE_DIRECTORY

Set to true when AD is used

APPLICATION_SECURITY_AUTHENTICATION_

LDAP_DOMAIN

Domain name

APPLICATION_SECURITY_AUTHENTICATION_

LDAP_DOMAIN_USERS

Allows LDAP authentication for any of two forests in one domain. The default value for this setting is false. To authenticate users from just one

Page 45: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 41

PROPERTY DESCRIPTION

domain via LDAP, set this property to true and

then set the correct domain in the property APPLICATION_SECURITY_

AUTHENTICATION_LDAP_DOMAIN

APPLICATION_SECURITY_AUTHENTICATION_

LDAP_SERVER

Full computer name of the LDAP server

APPLICATION_SECURITY_AUTHENTICATION_

LDAP_MANAGE_DN

APPLICATION_SECURITY_AUTHENTICATION_

LDAP_MANAGE_PASSWORD

Sets the user name and password to apply to connect to LDAP server when LDAP_ACTIVE_DIRECTORY=false

If LDAP_ACTIVE_DIRECTORY = true, these

properties may be omitted from the config file.

These credentials are also used to add multiple users to Knowledge Hub using LDAP query

APPLICATION_SECURITY_AUTHENTICATION_

LDAP_SEARCH_BASE

Domain name components (e.g., DC=altair,DC=com if domain is altair.com)

APPLICATION_SECURITY_AUTHENTICATION_

LDAP_SEARCH_FILTER

Filter used to search for LDAP users

APPLICATION_SECURITY_AUTHENTICATION_

LDAP_USER_ROLES

User role(s) for created users

APPLICATION_SECURITY_AUTHENTICATION_

LDAP_ADMIN_USERS

List of users automatically created with the Super Administrator role in Knowledge Hub (if USERS_PROVISIONED = false). When this

list is provided, there is no need to login as an administrator and create the first LDAP user.

APPLICATION_SECURITY_AUTHENTICATION_

LDAP_ROLEMAPPING

true to enable role-mapping in Knowledge Hub;

false to disable

APPLICATION_SECURITY_AUTHENTICATION_

LDAP_GROUPMAPPING

true to enable group-mapping in Knowledge

Hub; false to disable

APPLICATION_SECURITY_AUTHENTICATION_

LDAP_ROLESMAP

Mapping of Knowledge Hub roles to LDAP groups

NOTES:

• The property APPLICATION_SECURITY_AUTHENTICATION_LDAP_SEARCH_FILTER uses the

format "username@domain".

• If a user does not specify the domain in the login form, the value in APPLICATION_SECURITY_AUTHENTICATION_LDAP_DOMAIN will be used as the domain.

• LDAP search attributes should have values in "username@domain" format.

• If the property USERS_PROVISIONED is set to TRUE, and the user is not included in the ADMIN_USERS

list, an error (i.e., “Users %user_login% does not exist”) is returned when the user logs into the application. In this case, the user must be manually added through the User Management page (via LDAP) of Knowledge Hub.

• If the property USERS_PROVISIONED is set to FALSE, and the user exists in Active Directory, a new

user is created upon login to Knowledge Hub. This user’s profile will include a login, last name, and first name, and s/he will have the role(s) specified in USER_ROLES.

• If the user exists in Active Directory, and the new user is included in the ADMIN_USERS list, the user can

log into Knowledge Hub and this user will have the role Super Administrator regardless if the property USERS_PROVISIONED is set to TRUE or FALSE.

Page 46: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 42

To enable role/group mapping, set the following properties:

• APPLICATION_SECURITY_AUTHENTICATION_LDAP_ROLEMAPPING – true to enable role

mapping; false otherwise

• APPLICATION_SECURITY_AUTHENTICATION_LDAP_GROUPMAPPING - true to enable group

mapping; false otherwise

• APPLICATION_SECURITY_AUTHENTICATION_LDAP_ROLESMAP_%role_id1%:

“%GroupName1, GroupName2%” – Mapping of first Knowledge Hub role to LDAP groups

• APPLICATION_SECURITY_AUTHENTICATION_LDAP_ROLESMAP_%role_id2%:

“%GroupName1, GroupName2%” – Mapping of second Knowledge Hub role to LDAP groups

2. Apply settings to core-api by deleting pod(s) of <namespace>-core-api Deployment or by scaling

the Deployment to 0 and then back to the desired number of pods.

SETTING UP SECURITY ASSERTION MARKUP LANGUAGE (SAML) AUTHENTICATION

Knowledge Hub supports SAML authentication. The following general steps must be carried out to configure SAML for Knowledge Hub.

Steps:

1. Prepare a Knowledge Hub installation.

2. Download and install Amazon Corretto 11.0.4+ (e.g., 11.0.7).

3. Configure Okta IDP.

4. Configure SAML properties in the Knowledge Hub config file.

5. Run Helm upgrade.

The sections below describe how to perform Steps 3–5 in detail.

Configuring Okta IDP

Steps:

1. Login to your Okta account. The Developer Console displays as the default view.

2. Click the upper left-hand corner of this console, and then choose Classic UI.

Page 47: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 43

3. In the dashboard that displays, click Add Applications.

4. Click Create New App.

5. In the dialog box that appears, select SAML 2.0, and then click Create.

6. In the General Settings section, enter Spring Security SAML in the App name box and then click Next.

Page 48: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 44

Next, you must configure your SAML settings.

7. In Part A of the Configure SAML section, paste the following URLs

• Single sign on URL: <kh-host>/saml/SSO (e.g., https://bp-south.aws.dev-

altair.com:8443/saml/SSO)

• Audience URI (SP Entity ID): <kh-host>/saml/metadata (e.g., https://bp-south.aws.dev-

altair.com:8443/saml/metadata)

IMPORTANT: The URI indicated should match the value specified for application.security.

authentication.saml.localEntityId in the Knowledge Hub config file.

Page 49: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 45

8. (REQUIRED) Configure SAML user attributes.

For user creation, Knowledge Hub requires the following attribute names mapped in the configuration file:

• Login – login

• First name – firstName

• Last name – lastName

• Email – emailAddress

Add the following attribute statements:

You can modify these attributes at a later time by going to Applications > <Your APP> > General > SAML Settings > Edit > Configure SAML > Attribute Statements in Okta.

9. (OPTIONAL) Configure SAML groups.

Role mapping for Knowledge Hub may be configure in Okta. To do so, specify mappings for groups in the Group Attribute Statements section.

These groups will be mapped to the Knowledge Hub config file. You can modify these attributes at a later time by going to Applications > <Your APP> > General > SAML Settings > Edit > Configure SAML > Group Attribute Statements in Okta.

10. Click Next when you are finished.

Your SAML configuration is completed.

Page 50: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 46

11. To complete role mapping for groups, go to Applications > <Your APP> > Assignments and assign the application to groups.

Configuring SAML Properties in Core-API Properties

Steps:

1. (REQUIRED) Copy aws-saml-values.yaml from the knowledgehub/example-values folder to the

setup folder.

2. (REQUIRED) Generate a .jks keystore keypair and copy this file to the setup folder. You must use at least jdk Amazon Corretto 11.0.4.+ for the keytool command.

Example script: jks-generator.sh

#!/bin/bash

ALIAS=privatekeyalias

CERTIFICATE_FILE=certificate.cer

KEYSTORE_FILE=saml-keystore.jks

keytool -genkeypair -alias $ALIAS -keypass samplePrivateKeyPass

-keystore $KEYSTORE_FILE -keyalg RSA -sigalg SHA256WithRSA

keytool -exportcert -keystore $KEYSTORE_FILE -alias $ALIAS -

file $CERTIFICATE_FILE

$ bash jks-generator.sh

Enter keystore password: secret

Re-enter new password: secret

Page 51: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 47

You will need to save two values that will be used by KnowledgeHub: the alias and the key-store password.

These values should be saved to create secrets.

As outputs, you will receive two files: saml-keystore.jks and certificate.cer.

Note: The key and signature algorithms supplied for keypair generation should match the values provided in the Okta application configuration, for example, -keyalg RSA -sigalg RSA-SHA256WithRSA.

To check these values, in Okta, go to Applications > <Your APP> > General > SAML Settings > Edit > Configure SAML > Show Advanced Settings.

3. (REQUIRED) Create saml-metadata.xml to read IDP metadata by using one of two ways:

• Create an empty file named saml-metadata.xml and place it in the Knowledge Hub setup folder or

• Create saml-metadata.xml from your SAML IDP metadata source

4. (REQUIRED) Modify the Knowledge Hub config file \knowledgehub\example-values\aws-saml-

values.yaml as follows.

core-api:

config:

authentication:

provider: saml

saml:

localEntityId: <Audience URI (SP Entity ID)>

idpMetadataUrl: <IDP metadata public URL>

fileMetadata: <true/false> #if true, Knowledge Hub uses

a file-based metadata source

singleLogout: <true/false> #if true, SAML Single Logout

should be configured for IDP

attribute-mapping:

login: login

first-name: firstName

last-name: lastName

Page 52: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 48

email: emailAddress

user-roles: #default role for user

- 2

role-mapping: <true/false> #enables role mapping

rolesmap: <mapping of roles to groups>

Default Properties

PROPERTY DESCRIPTION

localEntityId The value provided in Audience URI (SP Entity ID) in Okta

idpMetadataUrl

The IDP public metadata URL.

To obtain this value, go to Applications > <Your APP> > Sign On > Identity Provider Metadata and then click on the Identity Provider metadata link. The URL in the address bar of the popup window is your idpMetadataUrl (e.g., https://dev-

320573.okta.com/app/exkhbq6uo1au

BFrIs4x6/sso/saml/metadata)

fileMetadata Boolean property to enable file-based metadata source. If set to true, Knowledge Hub will use saml-metadata.xml for

Service Provider configuration.

attribute-mapping Mapping between assertion attributes and Knowledge Hub users to create.

user-roles Default user roles for Knowledge Hub user creation in the case when role-mapping is set to false or no groups are specified in

the attribute statements

role-mapping Boolean property to enable role mapping against SAML attribute statements

rolesmap Mapping for SAML assertion roles.

singleLogout Boolean property to enable Single Logout for Knowledge Hub. This property must be set to true if single logout is to be enabled.

Additional SAML Properties

PROPERTY DESCRIPTION

idp-metadata-file-path File path for file-based IDP metadata. Default value: /saml/saml-metadata.xml

signing-algorithm

Sets the signing algorithm to use when signing the SAML messages. Default value: http://www.w3.org/2001/04/

xmldsig-more#rsa-sha256

response-skew

Sets maximum difference between local time and time of the assertion creation which still allows message to be processed. Basically determines maximum difference between clocks of the

IDP and SP machines. Default value: 60s

max-authentication-age Sets maximum time between users authentication and processing

of an authentication statement. Default value: 7200s

authn-request-binding

Sets binding to be used for for sending SAML message to IDP.

Default value:

❑ urn:oasis:names:tc:SAML:2.0:

bindings:HTTP-POST

Possible values:

Page 53: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 49

❑ urn:oasis:names:tc:SAML:2.0:

bindings:HTTP-POST

❑ urn:oasis:names:tc:SAML:2.0:

bindings:HTTP-Redirect

❑ urn:oasis:names:tc:SAML:2.0:

bindings:PAOS

❑ urn:oasis:names:tc:SAML:2.0:

profiles:holder-of-key:SSO:browser

For example:

---

core-api:

config:

authentication:

provider: saml

saml:

localEntityId: "https://bp-south.aws.dev-

altair.com/saml/metadata"

idpMetadataUrl: "https://dev-

119332.okta.com/app/abcd123bgMSxfmtUJ4x6/sso/saml/metadata"

fileMetadata: false #enable file-based IDP metadata

source

singleLogout: true #if true SAML SLO should be

configured for IDP

attribute-mapping:

login: login

first-name: firstName

last-name: lastName

email: emailAddress

user-roles: #default role for user

- 2

role-mapping: true #enable role mapping

rolesmap:

3:

- “Analyst”

8:

- “Admin”

Page 54: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 50

The final Helm setup folder should include the following files.

Running Helm Upgrade

Steps:

1. Prepare KnowledgeHub Enterprise installation with namespace and certificate secrets.

2. (REQUIRED) Create SAML secrets.

2.1. saml-meta secret. Run the following command from the installation folder:

kubectl create secret generic -n <your-namespace> saml-meta --

from-file ./saml-metadata.xml --from-file ./saml-keystore.jks

2.2. saml-secret secret. Run the following command from the installation folder:

kubectl create secret generic -n <your-namespace> saml-secret --from-

literal APPLICATION_SECURITY_AUTHENTICATION_SAML_SSL_KEY_ALIAS=<your-

alias> --from-literal

APPLICATION_SECURITY_AUTHENTICATION_SAML_SSL_KEY_STORE_PASSWORD=<your-

secret>

IMPORTANT: Change the <your-alias> and <your-secret> values according to the keystore values from the .jks keystore keypair and copy the files to the setup folder step.

3. (REQUIRED) Run helm upgrade --install by adding aws-saml-values.yaml to the following command to

apply settings for KnowledgeHub SAML configuration.

helm upgrade --install --namespace <your-namespace> -f aws-

medium-values.yaml,./cipher/cipher_config.yaml,aws-saml-

values.yaml <your-release> ./knowledgehub/knowledgehub-*.tgz

Page 55: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 51

KNOWN ISSUE: In some cases following, after Steps 1-3 the core-api pod may end up in a crashloop state. To fix this issue:

1. Delete the regsecret form <your-namespace>

kubectl delete secret -n <your-namespace> saml-secret saml-meta

2. Redo Step 2 to recreate the necessary SAML certificates.

3. Delete the core-api pod

kubectl delete pod -n <your-namespace> <core-api-pod-name>

The pod should restart and come to a running state.

Advanced SAML Logging for Troubleshooting

By default, SAML-related logs are hidden for security purposes. In case troubleshooting is necessary, add the following properties to the core-api ConfigMap in k8s.

❑ "LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_SECURITY_SAML":"DEBUG",

❑ "LOGGING_LEVEL_ORG_OPENSAML":"DEBUG",

❑ "LOGGING_LEVEL_PROTOCOL_MESSAGE":"DEBUG"

Other Optional Configurations

Configuring Single Logout

Steps:

1. Go to Applications > <Your APP> > General > SAML Settings > Edit > Configure SAML > Show Advanced Settings.

2. Tick the box provided to Enable Single Logout.

3. Add the following parameters:

• Single Logout URL: <kh-host>/saml/SingleLogout (e.g., https://bp-south.aws.dev-

altair.com:8443/saml/SingleLogout)

• SP Issuer: This value should be identical to Audience URI (SP Entity ID) provided in the Okta SAML configuration

Page 56: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 52

• Signature Certificate: Upload the certificate.cer file obtained when you generate your .jks keystore

keypair

4. To enable this feature in Knowledge Hub, the singleLogout property in Helm must be set to true; otherwise,

SLO will not be implemented.

5. Save your settings.

Configuring Assertion Encryption

Steps:

1. Go to Applications > <Your APP> > General > SAML Settings > Edit > Configure SAML > Show Advanced Settings.

2. Enable the Assertion Encryption option.

3. Provide the corresponding encryption algorithm and key transport algorithm.

4. Save your settings.

SETTING UP OAUTH2.0 AUTHENTICATION

The following steps describe how to implement OAuth2.0 authentication in Knowledge Hub.

Registering the Knowledge Hub Application to Azure Active Directory

Steps:

1. Sign in to the Azure portal.

2. In the left-hand navigation pane, select the Azure Active Directory service, and then select App registrations (Preview) > New registration.

3. When the Register an application page appears, enter your application's registration information:

• Name - Enter a meaningful application name that will be displayed to users of the app.

• Supported account types - Select which account you would like your application to support.

Accounts in this organizational directory only – Select this option if you are building a line-of-business (LOB) application. This option is not available if you are not registering the application in a directory. This option maps to Azure AD only single-tenant.

Accounts in any organizational directory - Select this option if you would like to target all business and educational customers. This option maps to an Azure AD only multi-tenant.

Page 57: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 53

Accounts in any organizational directory and personal Microsoft accounts - Select this option to target the widest set of customers. This option maps to Azure AD multi-tenant and personal Microsoft accounts.

• Redirect URI – <kh-host>/login/oauth2/code/knowledgehub

4. When finished, select Register.

5. Copy the Application ID from the app's Overview page. This ID is the client_id, which you will need to modify the config file.

6. Select the Certificates & Secrets section from the app's Overview page.

7. Select New client secret.

8. Add a description for your client secret, select a duration, and then click Add.

9. After saving the configuration changes, the right-most column will contain the client_secret value, which you will need to update the Knowledge Hub config file.

More information on registering an app on Azure AD can be found in https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app.

Configuring Core-API Properties

Steps:

1. Update <namespace>-core-api properties in ConfigMaps. You can do this by using kubectl edit cm

<namespace>-core-api in a terminal connected to your cluster or UI tools such as Kubernetes Dashboard

or Google Cloud Platform console.

"APPLICATION_SECURITY_AUTHENTICATION_PROVIDER": "oauth2"

"APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_CLIENT_CLIENTID":

"<OAUTH2_CLIENT_ID>"

"APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_CLIENT_CLIENTSECRET"=

"<OAUTH2_CLIENT_SECRET>"

"APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_CLIENT_ACCESSTOKENURI":

"https://login.microsoftonline.com/common/oauth2/token"

"APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_CLIENT_

USERAUTHORIZATIONURI": "https://login.microsoftonline.com/common/

oauth2/authorize"

"APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_CLIENT_JWKURI":

"https://login.microsoftonline.com/common/discovery/keys"

"APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_CLIENT_SCOPE":

"openid,https://graph.microsoft.com/user.read"

"APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_RESOURCE_USERINFOURI":

"https://graph.microsoft.com/v1.0/me"

"APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_USER_ROLES": "<user

role id>"

"APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_ADMIN_USERS": "<users>”

"APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_ATTRIBUTE_MAPPING_

LOGIN": "upn"

"APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_ATTRIBUTE_MAPPING_

FIRST_NAME": "given_name"

"APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_ATTRIBUTE_MAPPING_

LAST_NAME": "family_name"

Page 58: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 54

"APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_ATTRIBUTE_MAPPING_

EMAIL": "upn"

"APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_ATTRIBUTE_MAPPING_

PHONE_NUMBER": "telephonenumber"

where:

• APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_CLIENT_CLIENTID – is the client ID

• APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_CLIENT_CLIENTSECRET – is the client secret

• APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_USER_ROLES – default role of users added to Knowledge Hub

• APPLICATION.SECURITY_AUTHENTICATION_OAUTH2_ADMIN_USERS – users with the Super Administrator role in Knowledge Hub

• APPLICATION_SECURITY_AUTHENTICATION_OAUTH2_ATTRIBUTE_MAPPING – settings used to add users by Azure AD query

2. Apply settings to core-api by deleting pod(s) of <namespace>-core-api Deployment or by scaling

the Deployment to 0 and then back to the desired number of pods.

Page 59: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 55

[6] UPDATING KNOWLEDGE HUB

UPDATING THE APPLICATION

The following steps are used to update an existing Knowledge Hub Enterprise application (e.g., 2.4.1) to a newer version (e.g., 2.4.2).

We recommend that you clear the /libs folder (but retain any “custom” drivers you may have added) before

updating Knowledge Hub. Upgrading the application does not remove outdated drivers from this folder and may cause issues (e.g., the application will not start or some connections cannot be completed) when the application is run.

Steps:

1. Download and unzip a new Knowledge Hub Enterprise installer archive.

2. Merge the /cipher/ folder and values file(s) to the new installer.

3. Ensure that no exports are running and cancel running exports, if any.

4. Delete the service redit-headless by using the following command: `kubectl delete service <namespace name>-redis-headless`.

5. Run `helm upgrade --install -–force -–recreate-pods --namespace <Knowledge Hub namespace name> -f ./cipher/cipher_config.yaml -f values.yaml <release_name> ./knowledgehub/knowledgehub-*.tgz` to update Knowledge Hub to version 2.4.1.

UPDATING THE LICENSING TYPE

The licensing type employed by Knowledge Hub may be updated any time you wish.

From File Licensing to HWU Licensing

Steps:

1. Edit values.yaml and add following properties:

core-api:

config:

optionalEnv:

APPLICATION_LICENSE_PROVIDER: remote

license-api:

replicaCount: 1

config:

yaml:

application:

license:

provider: hwu

Page 60: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 56

hwu:

host: "<license server port>@<license server

host>" # e.g. [email protected]

2. Update your deployment using the following command:

helm upgrade --install --namespace <knowledge hub namespace> -f

<aws-values-yaml>,<secret-values-yaml> <knowledge hub release

name> <installer folder>/knowledgehub/knowledgehub-*.tgz

From HWU Licensing to File Licensing

Steps:

1. Edit values.yaml and add following properties:

core-api:

config:

optionalEnv:

APPLICATION_LICENSE_PROVIDER: local

license-api:

replicaCount: 0

config:

yaml:

application:

license:

provider: local

2. Upload the license secret by using the following command:

kubectl create secret generic -n <knowledge hub namespace>

license --from-file license.lic

3. Update the Knowledge Hub deployment by using the following command:

helm upgrade --install --namespace <knowledge hub namespace> -f

<aws-values-yaml>,<secret-values-yaml> <knowledge hub release

name> <installer folder>/knowledgehub/knowledgehub-*.tgz

Page 61: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 57

UPDATING THE CORE-API PROPERTIES FILE FOR FILE SYSTEM CONNECTIONS

Previous versions of Knowledge Hub allowed users with the appropriate privileges (i.e., users with the roles Administrator, Super Administrator, or Advanced) to create connections to file systems straightaway. However, in Knowledge Hub 2.4.1, system administrators must specify root (base) paths to file folders to which users can create connections in the configuration file before these connections can be made. This improvement provides greater system security but also requires some work when upgrading from a lower version of the application.

Specifically, base paths must be provided for all file system connections created in previous versions of Knowledge Hub to be able to continue using these connections and accessing the necessary data sources from these connections in Knowledge Hub 2.4.1.

Steps:

1. After upgrading to Knowledge Hub 2.4.1, open the ConfigMap <namespace>-core-api file and then add

the following properties:

“APPLICATION_IO_CONNECTION_FILESYSTEM_ROOTPATHS_ROOT_PATH”:

“/var/swarm/file-library”

“APPLICATION_IO_CONNECTION_FILESYSTEM_ROOTPATHS_ROOT_PATH2”:

“/var/swarm/file-library2”

where:

/var/swarm/file-library – is the path to one directory

/var/swarm/file-library2 – is the path to another directory

IMPORTANT: Base paths are case-sensitive. When specifying a base path to use for file system connections, ensure that the case for all folder names, including the drive letter, are provided exactly as formatted.

NOTES:

• All root paths must be unique.

• Multiple root paths can be specified by using the properties ROOT_PATH, ROOT_PATH2, ROOT_PATH3, etc.

• If multiple paths contain the same start path (e.g., path1: var/swarm/file library; path2: var/swarm/file library/reports), these paths are divided into a root path (i.e., var/swarm/file library) and an extended path (i.e., /reports). Connections to these two paths may then be created.

2. Restart the core-api pod(s).

3. Log into Knowledge Hub 2.4.1 and then click Connections.

4. Select a file system connection from the Connections list to edit it.

5. Use the Base Path drop-down to select the correct file system base path for the connection. Add an extended path if necessary.

6. Save the connection.

If the necessary base paths are not specified in the config file, the warning “There are no base paths defined. Please contact the administrator.” is returned:

❑ When using a pre-defined file system connection

❑ When adding/editing a data source from a pre-defined file system connection

❑ When opening a workspace with a data source from a pre-defined file system connection:

Page 62: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 58

❑ When exporting a data source from a pre-defined file system connection

For example:

Page 63: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 59

[7] DELETING KNOWLEDGE HUB ENTERPRISE

DELETING KNOWLEDGE HUB ENTERPRISE SERVER

To delete the Knowledge Hub Enterprise helm chart and configuration, run:

helm del --purge <Knowledge Hub release name>

To get <Knowledge Hub release name>, run helm ls and find the Knowledge Hub Enterprise release name.

This command does not delete Persistent Volume Claims and Persistent Volumes. You can install Knowledge Hub Enterprise with helm once more without data loss.

To delete Knowledge Hub Enterprise Server completely, delete the Kuberentes namespace with the command:

kubectl delete ns <Knowledge Hub namespaces>

To get a list of available namespaces, run kubectl get ns.

DELETING MODULES

Deleting the Tracer (Jaeger)

1. Delete the jaeger-operator helm chart:

$ helm del jaeger-operator --purge

2. Delete the Jaeger components:

$ kubectl delete customresourcedefinition

jaegers.io.jaegertracing

Deleting the Logger (ELK Stack)

To delete the logger, run:

helm del --purge <elk release name>

and then delete Kuberentes namespace: kubectl delete ns <logging namespace>.

Page 64: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 60

Removing Monitoring (Grafana)

To remove monitoring, run:

helm del --purge <monitoring release name>

and then delete the Kuberentes namespace: kubectl delete ns <monitoring namespace>.

UTILITIES CONFIGURATION

To configure utilities for Knowledgeh Hub Enterprise Server, run utils.sh <knowledge hub helm

release> <knowledge hub helm release> from the ./utils/ directory and select:

❑ 1 - Show libraries in the cluster /libs folder

❑ 2 - download libraries to the './libs' folder - Download libraries on the local machine in the ./utils/libs from

cluster /libs folder

❑ 3 - Upload libraries from the local machine folder ./utils/libs into the cluster /libs folder. After

execution, all services must be restarted to apply changes.

❑ 4 - Removes libraries from the cluster /libs folder. After execution, all services must be restarted to apply

changes.

❑ 5 - Get default tokens for the Knowledge Hub namespace

❑ 6 - Update your Knowledge Hub license file. Before execution, copy a new version of license.lic to the folder ./utils/

❑ 7 - Restart all services of the Knowledge Hub

❑ 8 - Restore Knowledge Hub databases from the '.utils/backup/<date>' folder

❑ 9 – Create backup Knowledge Hub database in '.utils/backup/<date>'

❑ 10 - Generate cipher keys for Knowledge Hub chart and patch the application with it (required)

❑ 11 – Upload java-special-agent

❑ 12 – Create service accounts

❑ 13 – Exit the utils menu

Page 65: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 61

[8] ELASTIC LOG EXPORT/IMPORT FOR KNOWLEDGE HUB ENTERPRISE

EXPORTING ELASTICSEARCH TO AWS S3

Elasticsearch logs can be exported to an AWS S3 bucket in JSON format.

Steps:

1. Create an S3 bucket for backup, e.g., elasticsearch-dump-bucket.

2. The file elasticsearch-export-job.yaml is necessary to export logs. Configure elasticsearch-

export-job.yaml to specify S3 details (e.g., bucket, access key, secret access key) and query date.

- name: BUCKET

value: "elasticsearch-dump-bucket"

- name: ACCESS_KEY

value: "<ACCESS_KEY>"

- name: SECRET_ACCESS_KEY

value: "<SECRET_ACCESS_KEY>"

By default, logs will be exported for the last day. To change the date, add the following properties:

- name: FROM_DATE

value: "2019-05-15"

- name: TO_DATE

value: "2019-05-15"

3. Deploy and run the following k8s job.

kubectl apply -n logger -f elasticsearch-export-job.yaml

Page 66: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 62

IMPORTING LOGS IN K8S ELK

Steps:

1. Configure k8s port forwarding for the elk-elasticsearch-client service.

kubectl port-forward -n logging service/elk-elasticsearch-

client 9202:9200

2. Install elasticdump from the link https://www.npmjs.com/package/elasticdump

3. Run import in `logstash-aetna-2019-05-13-2019-05-15` collection.

elasticdump --input=./elasticsearch-backup-2019-05-13-2019-05-

15.json --output=http://localhost:9202/logstash-aetna-2019-05-

13-2019-05-15

Page 67: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 63

[9] MIGRATING (UPGRADING) WINDOWS INSTALLATIONS TO A CLUSTER

BACKING UP/RESTORING KNOWLEDGE HUB

Backing Up Windows Installations

To backup Windows installations, the following required variables must be set:

❑ JAVA_HOME - Location of java installation

❑ PG_DUMP - Location of PostgreSQL pg_dump executable

Run the following commands from ./single-server/bin/utils/:

Windows Backup Example

SET JAVA_HOME=C:\Program Files\Java\<jdk/jre folder>

SET PG_DUMP="C:\Program Files\PostgreSQL\11\bin\pg_dump.exe"

windows-backup.bat

The parameters provided in the example above should be changed according to actual file locations on the given system.

If the error “C:\Program' is not recognized as an internal or external command, operable program or batch file” appears, change the first command to “SET "JAVA_HOME=C:\Program Files\Java\<jdk/jre folder>"”.

The components will be backed up in ./single-server/bin/utils/backup/<date_time> (e.g.,

./single-server/bin/utils/backup/2019-03-06_07-48-51).

After successful backup, the following files are stored in the backup folder: dataengineapi_db.gz,

newserver_db.gz, fs-file_library.tar, and fs-libs.tar,.

Backing Up Linux Enterprise Installations

Knowledge Hub Enterprise Server supports the backup and restoration of the following components.

❑ meta-db – the PostgreSQL databases

❑ file-system – the file-libraries and libs docker volumes

Page 68: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 64

To backup Knowledge Hub Enterprise Server, run the following command from ./bin/utils/.

./linux-backup.sh

The components will be backed up in ./bin/utils/backup/<date_time> (e.g.:

./bin/utils/backup/2019-03-06_07-48-51).

After successful backup, the following files are stored in the backup folder: dataengineapi_db.gz,

newserver_db.gz, fs-file_library.tar, and fs-libs.tar

Restoring Backed Up Installations via Kubernetes

To restore backups of Linux Single Server or Windows installations, configure the backup_folder_path

variable in <swarm-enterprise>/conf/swarm.yaml and then run <swarm-

enterprise>/bin/utils.sh with option 8.

Windows Backup

./utils.sh # option 8

Logins to some connections (e.g., Google Drive) may need to be refreshed after restoring Knowledge Hub Enterprise Server.

Page 69: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 65

[10] MANAGING CIPHER KEYS

Cipher keys are used in Knowledge Hub for encryption and authentication. These keys must be provided when restoring Knowledge Hub from a backup or when updating Knowledge Hub Linux Enterprise Server.

CREATING CIPHER KEYS

If Knowledge Hub Enterprise Server is newly installed, generate cipher keys and a yaml file with these keys. To do so, run ./utils/utils.sh and select item 10 to generate cipher keys for KnowledgeHub helm chart.

When the keys have been generated, you will receive the message "INFO: Cipher keys for KnowledgeHub chart have been successfully generated" and a new folder appears in <installer folder>/cipher/ with the following

files:

❑ knhub.key.pub

❑ knhub.key

❑ cipher_config.yaml

EXTRACTING CIPHER KEYS

To extract encryption keys from Knowledge Hub Enterprise:

Steps:

1. Find the '<namespace name>-secret' secret in the Kubernetes Dashboard for the Knowledge Hub

Enterprise namespace.

2. Click the Edit button to open this secret for editing as a JSON file.

3. Find APPLICATION_SECURITY_AUTHENTICATION_XAUTH_SECRET, APPLICATION_ SECURITY_CIPHER_KEYPAIR_PRIVATEKEY, and APPLICATION_SECURITY_CIPHER_ KEYPAIR_PUBLICKEY properties.

4. Save the keys provided.

These values are encrypted and can be used to restore Knowledge Hub Linux Enterprise Server only.

You can view decrypted data from the secret using the Kubernetes Dashboard. To do so, open the <Knowledge Hub namespace>-secret and click on the eye icon near the keys in the secret.

UPDATING CIPHER KEYS

Cipher keys may need to be updated for several reasons:

❑ Installing Knowledge Hub Enterprise Server with cipher keys.

Prior to installation, the <installer folder>/cipher/cipher_config.yaml file must be updated

with the given (i.e., previously extracted, unencrypted) values if this file present. If not, copy the file from a backup. This file will be used for helm installation without any updates.

Page 70: Knowledge Hub Linux Enterprise Server v2.4.1 Installation ...€¦ · Knowledge Hub Linux Enterprise Server v2.4.1 Installation Guide 3 Logging ELK Stack is used to aggregate and

Altair Knowledge Hub Enterprise Server Installation Guide 66

❑ Updating cipher keys after deployment

Steps:

1. Find the '<namespace name>-secret' secret in the Kubernetes Dashboard for the Knowledge Hub

Enterprise namespace.

2. Click the Edit button to open this secret for editing as a JSON file.

3. Update the APPLICATION_SECURITY_AUTHENTICATION_XAUTH_SECRET, APPLICATION_ SECURITY_CIPHER_KEYPAIR_PRIVATEKEY, and APPLICATION_SECURITY_CIPHER_ KEYPAIR_PUBLICKEY properties with the encrypted values and apply changes.

4. Restart all containers where cipher keys are used and check that keys are updated.

When restoring Knowledge Hub, new cipher keys need not be generated with restoring Knowledge Hub Enterprise Server. Simply use the old values extracted from a previous deployment

Backup of the folder <installer folder>/cipher/, which is generated after running the utils.sh

script with option 10 is strongly recommended. This folder contains cipher keys and configuration values needed

to restore previous deployments.

MIGRATING CIPHER KEYS FROM WINDOWS TO ENTERPRISE SERVER INSTALLATIONS

Copy values from application-prod.yml to helm values using following mapping matrix:

APPLICATION-PROD.YML VALUES.YAML

application.security.

authentication.xauth.secret

global.config.authentication.

xauth.secret

application.security.cipher.

keyPair.privateKey

global.config.cipher.keyPair.

privateKey

application.security.cipher.

keyPair.publicKey

global.config.cipher.keyPair.

publicKey

Example of helm values:

global:

config:

cipher:

keyPair:

privateKey: <PUT_KEY_HERE>

publicKey: <PUT_KEY_HERE>

authentication:

xauth:

secret: <PUT_KEY_HERE>


Recommended