knowledge hub linux enterprise server v2.4.1 installation guide - … · 2020-04-14 ·...
TRANSCRIPT
Altair Knowledge Hub™ 2.4.2 ENTERPRISE SERVER INSTALLATION GUIDE
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
[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
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
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.
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
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
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
Altair Knowledge Hub Enterprise Server Installation Guide 5
❑ Service discovery and load balancing
❑ Secret and configuration management
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
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:
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
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
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
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:
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
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
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
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
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
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
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
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
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
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
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: ''
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
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.
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.
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
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 ®istry 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
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>
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.
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.
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.
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
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.
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.
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
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
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)
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",
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":
"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}))",
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],
}
}
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
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.
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.
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.
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.
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.
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
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
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:
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”
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
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
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.
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"
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.
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
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
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:
Altair Knowledge Hub Enterprise Server Installation Guide 58
❑ When exporting a data source from a pre-defined file system connection
For example:
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>.
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
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
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
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
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.
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.
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>