Skip to main content

Install Witboost

Witboost is installed in the customer environment and interacts with several external components (database, identity provider, versioning system, etc.). As each customer has a different infrastructure, Witboost tries to be as flexible as possible to accommodate such scenarios.

Before walking through the prerequisites, make sure you read the requirements.

Prerequisites​

Database​

Once the database has been provided, make sure to create the following databases, you will need them later:

  • core (required)
  • provisioning_coordinator (required)
  • marketplace (optional, it is needed if the MarketPlane module is enabled in your license)
  • witty (optional, it is needed if the Witty module is enabled in your license)
  • kgm (optional, it is needed if your organization decides to enable the Knowledge Graph Manager service)

If needed, the database names can be changed, but they must be changed accordingly in the configuration file (the values.yaml of the witboost helm chart). Refer to the following table to correctly reconfigure the databases.

Default databaseConfiguration reference
coreGlobals.dbs.coreDB
marketplaceGlobals.dbs.marketplaceDB
provisioning_coordinatorGlobals.dbs.provisioningCoordinatorDB
wittyGlobals.dbs.wittyDB
kgmGlobals.dbs.kgmDB
note

As remarked in the requirements:

  • witty and marketplace must have pg_vector extension enabled
  • core must have pg_crypto extension enabled

Versioning System​

note

The versioning system integration is not needed if you are performing a WCG-only installation

Witboost requires a versioning system to store templates, components, and other entities and to manage their lifecycle.

Gitlab is the preferred choice, but Azure DevOps, Bitbucket and GitHub are also supported.

Regardless of the one you pick, you will need to provide a token that has read permissions on the group/project where all Witboost repositories will be hosted.

info

It is important to know that Witboost will also create repositories in the same group/project. This is performed through the user personal token, which will have also write permissions. This decoupling guarantees that write operations are bound to the user, with the benefit of providing least privileges to the technical user, and allowing for a granular audit. More on this can be found here.

Directory Services​

Witboost supports OpenLDAP compatible vendors, as well as Active Directory and FreeIPA. Witboost interacts with a directory service for two main purposes:

  • Log in (Authentication)
  • Fetch of users/groups (Authorization)

On Prem AD or OpenLDAP/FreeIPA​

A bind user is necessary for authentication and to fetch users/groups on a specific search base. For how to configure an LDAP provider, you can refer to this documentation.

Entra ID (Former Azure AD)​

An Azure app registration must be configured to enable SSO and to fetch users/groups. One or more groups can be provided to narrow the company tree.

Follow the Microsoft Entra ID (Azure AD) provider documentation to create and configure your App Registration with the required permissions, and to set up the Azure AD provider in Witboost.

Authenticated Guest Users​

Witboost provides a temporary way of accessing the platform with authenticated credentials via a fixed set of guest users: guest_admin, guest_developer and guest_user. These users are described here and are useful to configure and test the rest of the platform while other more secure methods of authentication like the above-mentioned are being configured. These users are enabled in the platform if either:

  • The provided license file contains the credentials for a set or subset of guest users, and/or;
  • Credentials are configured for a set or subset of guest users. If credentials are provided both on configuration and license, the configuration values take precedence.

Upon the platform first installation, these users are registered on the platform, and if an RBAC preset is configured, assigned a specific role on the platform.

After you finished setting up a more secure authentication method, disable these users by following the steps explained here.

Platform​

Witboost's main components are installed in Kubernetes. As the platform is provided by the user, there can be several variations of the configurations, such as how the customer handles networking, TLS certificates, DNSs, etc. In the following paragraphs we list some considerations.

Docker Registry​

Witboost images are publicly accessible through a token that will be provided by AgileLab at installation time. If the network is capped and internet access forbidden, a docker registry must be provided, so that the necessary docker images will be imported.

Networking​

Witboost exposes a web interface that must be reachable by the users. To accomplish this, a TLS certificate and a domain name must be available.

TLS certificate​

Witboost leverages cert-manager to retrieve a valid certificate from Let’s Encrypt. It is anyway possible to configure Witboost with a customer provided certificate. When choosing let’s encrypt, it is important to decide the validation method, which can be particularly tricky in air-gapped scenarios.

If the customer already has certificates to use, they can be setup directly at ingress controller level, enforcing TLS termination on the ingress.

Domain​

Witboost leverages external-dns, which allows to control DNS records dynamically via Kubernetes resources in a DNS provider-agnostic way. This is usually used in on-cloud scenarios, where the records are updated in the cloud-specific DNS, accordingly delegated by the customer primary domain.

For example, in an AWS environment, the customer can provide a route53 zone (.witboost.customer.com), delegated from the customer main DNS (.customer.com). Witboost will leverage external-dns to synchronize the records in the route53 zone.

You can refer to DNS delegation for an overview on this topic.

note

External-dns can be configured in the external-dns block of the values.yaml.

note

The Kubernetes cluster must have the permissions to interact (read/write) with the DNS zone.

Secret management​

Witboost needs to use secrets (i.e. DB user, LDAP user, GitLab token, etc.).

They must be configured in a secret manager compatible with external-secrets. This is the list of compatible backends. The choice is usually driven by the cloud the cluster lives in, or by the customer company guidelines/policies.

If no backend is available, or the customer prefers to opt for a quicker approach, there are few options:

  • Secrets are "manually" created, it might be the case when the customer uses custom pipelines to deploy helm charts into Kubernetes.
  • The fake secret store is used: this is usually not recommended, as the secrets are stored in a yaml file that is pushed along with the chart, but it could be judged viable in playgrounds/poc environments

Regardless of the approach used, Witboost expects a kubernetes secret named "witboost-secrets" containing, among others, the following:

  • Database credentials
  • Azure AD/Entra ID credentials This secret is automatically created from external-secrets, and it will contain all the secrets that have been inserted in the configured secret store.
tip

As a reference of how to fill the secret manager (or directly the secret) an example fake secret store is provided in which a list of needed secrets for a basic installation can be found. This reference will be of help for filling the secret store, but also for the scenario where secrets are manually created.

Manually created secrets​

If external-secrets is not used, the secret called “witboost-secrets” must be created with all the items in it.

Installation​

Witboost is installed via its Helm chart, provided by Agile Lab.

Third-party installations​

Before proceeding with the installation of the witboost helm chart, make sure the following third-party deployments are present if needed.

External secrets

Unless you have opted for the manual creation of Kubernetes secrets, make sure external-secrets is installed. You can double-check it with the following command, which should return external-secrets CRDs:

$ kubectl get crds | grep externalsecrets

If it is not installed, you must

  • Install it following the official documentation.
  • Witboost now supports both older and newer versions(≥0.17.x) of External Secrets Operator (ESO).
    • Default: The chart uses apiVersion: external-secrets.io/v1 (introduced in ESO v0.17.0).
    • Override: If you are using an older ESO version (pre-v0.17.0), set globals.externalSecrets.apiVersion to external-secrets.io/v1beta1 in your values.yaml. Example configuration in values.yaml:
    globals:
      externalSecrets:
        # -- Set to external-secrets.io/v1beta1 for ESO < v0.17.0
        apiVersion: external-secrets.io/v1
  • Configure a ClusterSecretStore based on one of the available providers
  • Reference the ClusterSecretStore in the values.yaml (globals.externalSecrets.secretStore)

Run the following command to make sure it has been created and is in Ready state.

$ kubectl get clustersecretstore

You should find your secret store, in Ready state. The output should look like the following

$ kubectl get clustersecretstore
NAME                     AGE    STATUS   CAPABILITIES   READY
mysecretstore            296d   Valid    ReadWrite      True

Cert manager

If you are not using custom certificates but you plan to use the default TLS management configuration, make sure cert-manager is installed. You can double-check it with the following command, which should return cert-manager CRDs:

$ kubectl get crds | grep cert-manager

If it is not installed, you must

  • install it following the official documentation
  • configure a clusterIssuer, for example, the ACME one
  • reference the issuer in the values.yaml (globals.certManager.clusterIssuer)

Run the following command to make sure it has been created and is in Ready state.

$ kubectl get clusterIssuer

You should find your secret store, in Ready state. The output should look like the following

$ kubectl get clusterIssuer
NAME                     READY   AGE
letsencrypt-production   True    2y236d

External DNS

Make sure external secrets is installed. You can double-check it with the following command, which should return external-dns pod(s):

$ kubectl get pods --all-namespaces | grep external-dns

If it is not installed, you can either:

  • Install it following the official documentation
  • Enable it via the external-dns.enabled toggle of the values.yaml

Witboost Helm chart installation​

You are now ready to proceed with the Witboost installation.

Let's create a dedicated namespace, we will install Witboost in it:

$ kubectl create ns witboost

Create the regcred to access the Agile Lab docker registry (or whatever registry you host the images in):

$ kubectl create secret docker-registry regcred --docker-server=registry.gitlab.com --docker-username=witboost --docker-password="${REGISTRY_TOKEN}" -n witboost

In order to proceed to the witboost helm chart installation, a configuration file (i.e. values.yaml) must be prepared to properly configure Witboost depending on the aforementioned prerequisites.

tip

A reference values.yaml is provided and must be customized according to the installation environment.

Using the base file provided, look for the “CHANGEME” placeholders and configure them based on your setup. With the values.yaml prepared, you can proceed in installing the Witboost helm chart.

$ helm repo add --username <username> --password <access_token> witboost https://gitlab.com/api/v4/projects/40979925/packages/helm/stable
$ helm upgrade --install --rollback-on-failure <release_name> witboost/witboost -n <namespace> -f <my-values.yaml> --version X.Y.Z --timeout 10m
Helm 3 compatibility

The command above uses --rollback-on-failure, which is the Helm 4 flag. If you are using Helm 3, replace it with --atomic:

$ helm repo add --username <username> --password <access_token> witboost https://gitlab.com/api/v4/projects/40979925/packages/helm/stable
$ helm upgrade --install --atomic <release_name> witboost/witboost -n <namespace> -f <my-values.yaml> --version X.Y.Z --timeout 10m

For a full list of changes between Helm 3 and Helm 4, see the official Helm 4 overview.

After Helm finishes, you should:

  • Check that all pods are up and running
  • Check Ingresses and wait for DNS & TLS certificates to apply; if using external-dns and cert-manager it can take a couple of minutes
  • Go to the web UIs and ensure everything is reachable. The endpoints depend on how you have configured the values.yaml, you can check the ingresses
    • Ensure you can access Witboost UI
    • Ensure you can access Hasura UI
    • Ensure you can access the Documentation UI

Advanced configuration​

In the default Witboost setup, the instance is configured with default values, which are tailored for a generic installation, suitable for most use cases.

For advanced configuration of the main components, you can refer to their documentation