Install Rhize services

The final installation step is to install the Rhize services in your Kubernetes cluster.

Prerequisites

This topic assumes you have done the following:

• Set up Kubernetes and Configured Keycloak. All the prerequisites for those topics apply here.

• Configured load balancing for the following DNS records:

  Service	Domain
  Admin UI	rhize-ui.<YOUR_DOMAIN>
  Keycloak	rhize-auth.<YOUR_DOMAIN>
  GraphQL	rhize-api.<YOUR_DOMAIN>
  NATS	rhize-mqtt.<YOUR_DOMAIN>
  Grafana	rhize-grafana.<YOUR_DOMAIN>

  Note that rhize- is only the recommended prefix of the subdomain. Your organization may use something else.

Overrides

Each service is installed through a Helm YAML file. For some of these services, you might need to edit this file to add credential information and modify defaults.

Common values that are changed include:

• URLs and URL links
• The number of replicas running for each pod
• Ingress values for services exposed on the internet

Get client secrets.

1. Go to Keycloak and get the secrets for each client you’ve created.

2. Create Kubernetes secrets for each service. You can either create a secret file, or pass raw data from the command line.

   Caution How you create Kubernetes secrets depends on your implementation details and security procedures. For guidance, refer to the official Kubernetes topic, Managing Secrets using kubectl.

   With raw data, the command might look something like this.

   kubectl create secret generic libre-client-secrets \
   -n libre --from-literal=dashboard=<USER \
   --from-literal=libreAgent=123 \
   --from-literal=libreAudit=123 \
   --from-literal=libreBaas=KYbMHlRLhXwiDNFuDCl3qtPj1cNdeMSl \
   --from-literal=libreBPMN=123 \
   --from-literal=libreCore=123 \
   --from-literal=libreUI=123 \
   --from-literal=router=123
   

   As you install services through Helm, their respective YAML files reference these secrets.

Add the Rhize Helm Chart Repository

You must add the helm chart repository for Rhize.

1. Add the Helm Chart Repository

   helm repo add libre https://gitlab.com/api/v4/projects/42214456/packages/helm/stable
   

Install and add roles for the DB

You must install the libreBaas database service first. You also need to configure the libreBaas service to have roles in Keycloak.

If enabling the Audit Trail, also the include the configuration in Enable change data capture.

1. Use Helm to install the database:

   helm install -f baas.yaml libre-baas libre/baas -n libre
   

   To confirm it works, run the following command:

   kubectl get pods
   

   All statuses should be RUNNING.

2. Return to the Keycloak UI and add all libre roles to the admin group.

3. Proxy the http:8080 port on libre-baas-dgraph-alpha.

   kubectl port-forward -n libre pod/baas-baas-alpha-0 8080:8080
   

4. Get a token using the credentials. With curl, it looks like this:

   curl --location --request POST 'https://<customer>-
   auth.libre/realms/libre/protocol/openid-connect/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'grant_type=password' \
   --data-urlencode 'username=system@libre.com' \
   --data-urlencode 'password=<PASSWORD>' \
   --data-urlencode 'client_id=libreBaas' \
   --data-urlencode 'client_secret=<CLIENT_SECRET>'
   

5. Post the schema:

   curl --location --request POST 'http://localhost:<FORWARDED_PORT>/admin/schema' \
   --header 'Authorization: Bearer <TOKEN>' \
   --header 'Content-Type: application/octet-stream' \
   --data-binary '@<SCHEMA_FILE>'
   

   This creates more roles.

6. Go to Keycloak UI and add all new libreBaas roles to the ADMIN group.

If the install is successful, the Keycloak UI is available on its default port.

Install services

Each of the following procedures installs a service through Helm.

The syntax to install a Rhize service must have arguments for the following:

• The chart YAML file
• The packaged chart
• The path to the unpackaged chart or directory

Additionally, use the -n flag to ensure that the install is scoped to the correct namespace:

helm install <service_name> \
  -f <service-overide-file>.yaml \
  <path/to/directory> \
  -n <ns>

For the full configuration options, read the official Helm install reference.

NATS

NATS is the message broker that powers Rhize’s event-driven architecture.

Install NATS with these steps:

1. Modify the NATS Helm file with your code editor. Edit any necessary overrides.

2. Install with Helm:

   helm install nats -f nats.yaml libre/nats -n libre
   

Tempo

Rhize uses Tempo to trace BPMN processes.

Install Tempo with these steps:

1. If it doesn’t exist, add the Tempo repository:

   helm repo add grafana https://grafana.github.io/helm-charts
   

2. Modify the Helm file as needed.

3. Install with Helm:

   helm install tempo -f tempo.yaml grafana/tempo -n libre
   

Core

The Libre Core service is the custom edge agent that monitors data sources, like OPC-UA servers, and publishes and subscribes topics to NATS.

Requirements: Core requires the libreBaas and NATS services.

Install the Core agent with these steps:

1. In the core.yaml Helm file, edit the clientSecret and password with settings from the Keycloak client.

2. Override any other values, as needed.

3. Install with Helm:

   helm install core -f core.yaml libre/core -n libre
   

BPMN

The BPMN service is the custom engine Rhize uses to process low-code workflows modeled in the BPMN UI.

Requirements: The BPMN service requires the libreBaas, NATS, and Tempo services.

Install the BPMN engine with these steps:

1. Open bpmn.yaml Update the clientSecret and password for your BPMN Keycloak credentials.

2. Modify any other values, as needed.

3. Install with Helm:

   helm install bpmn -f bpmn.yaml libre/bpmn -n libre
   

Router

Rhize uses the Apollo router to unite queries for different services in a single endpoint.

Requirements: Router requires the GraphDB, BPMN, and Core services.

Install the router with these steps:

1. Modify the router Helm YAML file as needed.

2. Install with Helm:

   helm install router -f router.yaml libre/router -n libre
   

If the install is successful, the Router explorer is available on its default port.

Grafana

Rhize uses Grafana for its dashboard to monitor real time data.

Install Grafana with these steps:

1. Modify the Grafana Helm YAML file as needed.

2. Add the Helm repository

   helm repo add grafana https://grafana.github.io/helm-charts
   

3. Install with Helm:

   helm install grafana -f grafana.yaml grafana/grafana -n libre
   

If the install is successful, the Grafana service is available on its default port.

Agent

The Rhize agent bridges your plant processes with the Rhize data hub. It collects data emitted from the plant and publishes it to the NATS message broker.

Requirements: Agent requires the Graph DB, Nats, and Tempo services.

Install the agent with these steps:

1. Modify the Agent Helm file as needed.

2. Install with Helm:

   helm install agent -f agent.yaml libre/agent -n libre
   

Install UI

The UI is the graphical frontend to handle events and define work masters.

Requirements: The UI requires the GraphDB, BPMN, Core, and Router services.

After installing all other services, install the UI with these steps:

1. Forward the port from the Router API.

2. Open the UI Helm file. Update the envVars object with settings from the UI Keycloak client.

3. Modify any other values, as needed.

4. Install with Helm:

   helm install ui -f ui-overrides.yaml libre/admin-ui -n libre
   

If the install is successful, the UI is available on its default port.

Optional: Audit Trail service

The Rhize Audit service provides an audit trail for database changes to install. The Audit service uses PostgreSQL for storage.

Install Audit Service with these steps:

1. Modify the Audit trail Helm YAML file. It is recommended to change the PostgreSQL username and password values.

2. Install with Helm:

   helm install audit -f audit.yaml libre/audit -n libre
   

3. Create partition tables in the PostgreSQL database:

   create table public.audit_log_partition( like public.audit_log );
   select partman.create_parent( p_parent_table := 'public.audit_log', p_control := 'time',  p_interval := '1 Month', p_template_table := 'public.audit_log_partition');
   

For details about maintaining the Audit trail, read Archive the PostgresQL Audit trail.

Enable change data capture

The Audit trail requires change data capture (CDC) to function. To enable CDC in libre BAAS, include the following values for the Helm chart overrides:

alpha:
  # Change Data Capture (CDC)
  cdc:
    # Enable
    enabled: true
    # If configured for security, configure in NATS url. For example `nats://username:password@nats:4222`
    nats: nats://nats:4222
    # Adjust based on high-availability requirements and cluster size.
    replicas: 1

Enable Audit subgraph

To use the Audit trail in the UI, you must add the Audit trail subgraph into the router. To enable router to use and compose the subgraph:

1. Update the Router Helm chart overrides, router.yaml, to include:

# Add Audit to the router subgraph url override
router:
  configuration:
    override_subgraph_url:
      AUDIT: http://audit:8084/query

# If supergraph compose is enabled
supergraphCompose:
  supergraphConfig:
    subgraphs:
    AUDIT:
      routing_url: http://audit:8084/query
      schema:
        subgraph_url: http://audit:8084/query

2. Update the Router deployment

$ helm upgrade --install router -f router.yaml libre/router -n libre

Optional: calendar service

The Libre calendar service monitors work calendar definitions and creates work calendar entries in real time, both in the Graph and time-series databases.

Requirements: The calendar service requires the GraphDB, Keycloak, and NATS services.

Install the calendar service with these steps:

1. Create tables in the time series. For example:

   CREATE TABLE IF NOT EXISTS PSDT_POT(
     EquipmentId SYMBOL,
     EquipmentVersion STRING,
     WorkCalendarId STRING,
     WorkCalendarIid STRING,
     WorkCalendarDefinitionId STRING,
     WorkCalendarDefinitionEntryId STRING,
     WorkCalendarDefinitionEntryIid STRING,
     WorkCalendarEntryId STRING,
     WorkCalendarEntryIid SYMBOL,
     HierarchyScopeId STRING,
     EntryType STRING,
     ISO22400CalendarState STRING,
     isDeleted boolean,
     updatedAt TIMESTAMP,
     time TIMESTAMP,
     lockerCount INT,
     lockers STRING
   ) TIMESTAMP(time) PARTITION BY month
   DEDUP UPSERT KEYS(time, EquipmentId, WorkCalendarEntryIid);
   
   CREATE TABLE IF NOT EXISTS PDOT_PBT(
     EquipmentId SYMBOL,
     EquipmentVersion STRING,
     WorkCalendarId STRING,
     WorkCalendarIid STRING,
     WorkCalendarDefinitionId STRING,
     WorkCalendarDefinitionEntryId STRING,
     WorkCalendarDefinitionEntryIid STRING,
     WorkCalendarEntryId STRING,
     WorkCalendarEntryIid SYMBOL,
     HierarchyScopeId STRING,
     EntryType STRING,
     ISO22400CalendarState STRING,
     isDeleted boolean,
     updatedAt TIMESTAMP,
     time TIMESTAMP,
     lockerCount INT,
     lockers STRING
   ) TIMESTAMP(time) PARTITION BY month
   DEDUP UPSERT KEYS(time, EquipmentId, WorkCalendarEntryIid);
   
   CREATE TABLE IF NOT EXISTS Calendar_AdHoc(
     EquipmentId SYMBOL,
     EquipmentVersion STRING,
     WorkCalendarId STRING,
     WorkCalendarIid STRING,
     WorkCalendarDefinitionId STRING,
     WorkCalendarDefinitionEntryId STRING,
     WorkCalendarDefinitionEntryIid STRING,
     WorkCalendarEntryId STRING,
     WorkCalendarEntryIid SYMBOL,
     HierarchyScopeId STRING,
     EntryType STRING,
     ISO22400CalendarState STRING,
     isDeleted boolean,
     updatedAt TIMESTAMP,
     time TIMESTAMP,
     lockerCount INT,
     lockers STRING
   ) TIMESTAMP(time) PARTITION BY month
   DEDUP UPSERT KEYS(time, EquipmentId, WorkCalendarEntryIid);
   

2. Modify the calendar YAML file as needed.

3. Deploy with helm

   helm install calendar-service -f calendar-service.yaml libre/calendar-service -n libre
   

Optional: change service configuration

The services installed in the previous step have many parameters that you can configure for your performance and deployment requirements. Review the full list in the Service configuration reference.

Troubleshoot

For general Kubernetes issues, the Kubernetes dashboard is great for troubleshooting, and you can configure it to be accessible through the browser.

For particular problems, try these commands:

• Is my service running?

  To check deployment status, use this command:

   kubectl get deployments
  

  Look for the pod name and its status.

• Access service through browser

  Some services are accessible through the browser. To access them, visit local host on the service’s default port.

• I installed a service too early. If you installed a service too early, use Helm to uninstall:

  helm uninstall libreBaas
  

  Then perform the steps you need and reinstall when ready.