KX Insights Manual Installation

The section details how you would manually generate secrets for deploying the KX Insights Platform in a pre-configured Kubernetes Cluster and install the KX Insights Platform.

If this is your first time installing the KX Insights Platform you should follow the CLI installation instead of this guide.

These steps should only be used if you need more control over the installation than what the CLI provides.

Manual secret creation

Self-managed ingress certs

Once you have the certificate (ca.crt) and private key (ca.key), you can create a secret containing them.

kubectl create secret tls kxi-ingress-cert --cert=ca.crt --key=ca.key

The values file should then reference this secret as below.

global:
  ingress:
    certmanager: false
    tlsSecret: kxi-ingress-cert

License file

A valid license is required to run the KX Insights Platform. For instructions on how to obtain a license, please see here. The path to license file needs to be supplied as a secret to Kubernetes and referenced by the Helm charts.

Use the command below to create a license secret, where kx.lic is the path to your license file.

kubectl create secret generic kxi-license --from-file=license=kx.lic

The secret created is called kxi-license so the Helm value should reference this name in the global.license.secretName field here.

Image pull secrets

An image pull secret is required in order to pull images from a private Docker registry. Using your credentials for the Insights Nexus registry, you can create a secret for pulling these images.

kubectl create secret docker-registry kxi-nexus-pull-secret \
    --docker-username=<username> \
    --docker-password=<password> \
    --docker-server=registry.dl.kx.com

This creates a kxi-nexus-pull-secret secret, which should be referenced by the global.imagePullSecrets.name value here.

Client certificate issuer

The KX Insights Platform uses mutual TLS for clients publishing data into the system via RT. This requires the system to be configured with a certificate issuer to generate unique keys and certs for each client.

The command below generates a private key and signing certificate for the issuer resource.

Exit Container

You should not run these commands as root it will prevent them being accessed by non-root users. Instead exit the container and run on the source host.

LinuxmacOS

openssl genrsa -out ca.key 2048
openssl req -x509 -new -nodes -key ca.key -subj "/CN=insights.kx.com" -days 3650 -reqexts v3_req -extensions v3_ca -out ca.crt

openssl genrsa -out ca.key 2048
openssl req -x509 -new -nodes -key ca.key -subj "/CN=insights.kx.com" -days 3650 -reqexts v3_req -extensions v3_ca -out ca.crt -config /usr/local/etc/openssl@1.1/openssl.cnf

Now that the ca.crt and ca.key files have been created, you should re-access the the container by running the manage-cluster.sh script and apply the secret as follows from the container

kubectl create secret tls kxi-certificate --cert=ca.crt --key=ca.key

The secret is called kxi-certificate which should be referenced by the global.caIssuer.secretName value in the values file.

Keycloak passwords

Keycloak is used as the identity and access management platform for the KX Insights Platform.

The KX Insights Platform uses the Bitnami Helm chart to deploy Keycloak which by default creates random alphanumeric passwords if none are specified.

This can cause issues during upgrades, as described here, so we recommend that you preconfigure your Keycloak passwords to avoid this.

There are four passwords that are required

Password	Description
`admin-password`	This is the password for the Keycloak Admin UI
`management-password`	This is the password for the WildFly management user
`postgresql-postgres-password`	This is the password for the database superuser
`postgresql-password`	This is the password for the database user that Keycloak uses

These can be created using kubectl.

Passwords

in the secret generation commands below should be replaced with a password of your choosing and provided in place of the tags. It is not necessary that you use the same password for each one, you can have a unique password for each if desired.

kubectl create secret generic kxi-keycloak \
  --from-literal=admin-password=<PASSWORD> \
  --from-literal=management-password=<PASSWORD>
kubectl create secret generic kxi-postgresql \
  --from-literal=postgresql-postgres-password=<PASSWORD> \
  --from-literal=postgresql-password=<PASSWORD>

This creates two secrets called kxi-keycloak and kxi-postgresql. These should be set in the following values keycloak.auth.existingSecret and keycloak.postgresql.existingSecret respectively.

Values file

Before installing the KX Insights Platform it is necessary to provide a custom values file to configure the system appropriately. These include the secrets and resources created as part of the prerequisites here. The command below creates a simple global configuration file called insights.yaml.

Ingress host

The below tee command assumes the INSIGHTS_HOSTNAME environment variable has been set to the application's DNS record e.g. insights.example.com. If not you will need to update the file manually when this command is run.

tee insights.yaml << EOF
global:
  ingress:
    host: "${INSIGHTS_HOSTNAME}"

  license:
    secretName: kxi-license

  image:
    repository: registry.dl.kx.com
  imagePullSecrets:
    - name: kxi-nexus-pull-secret

  caIssuer:
    name: kxi-certificate
    secretName: kxi-certificate

keycloak:
  auth:
    existingSecret: kxi-keycloak
  postgresql:
    existingSecret: kxi-postgresql
EOF

More advanced configuration is detailed here.

Manual Helm install

The base system is hosted as a helm chart on the Insights Nexus. This can be added as a repo using the command below.

helm repo add --username <username> --password <password> kx-insights https://nexus.dl.kx.com/repository/kx-insights-charts

helm allows the user to view available versions of a chart with the command

helm search repo kx-insights/insights --versions

The chart can then be installed with the command below and using the insights.yaml created above.

helm install insights kx-insights/insights --version=<version> -f insights.yaml