Enabling embedded reporting

Edit online

Turbonomic includes an embedded reporting component that you can choose to enable when you install the platform. Use embedded reporting to understand application resource management trends and to share insights with stakeholders through reports and dashboards.

Embedded reporting runs as its own component, as part of the Turbonomic platform. This architecture enhances performance and reduces storage requirements. It stores a history of your managed environment and then presents selective snapshots of this history through a set of standard dashboards and reports. You can create your own dashboards and reports to focus on other areas of concern.

Embedded reports use TimescaleDB, which is an extension that is installed on a PostgreSQL database sever . These instructions are for the default configuration of TimescaleDB. As an alternative, you can configure an external deployment of TimescaleDB to manage your embedded reports data. For more information, see Configuring an External TimescaleDB.

The method that you use to enable embedded reports depends on the version status of your Turbonomic instance. Two options are available:

Run the enable_reporting.py script

You can use this option if you installed Turbonomic as a new VM image (OVA or VHD; see Installing on a Virtual Machine Image).
Edit the charts_v1alpha1_xl_cr.yaml file.

You can use this option if you installed Turbonomic as a Kubernetes cluster, not using the VM image for your Turbonomic installation. For more information, see Enabling embedded reporting in Kubernetes and Red Hat OpenShift Container Platform

You can also use this option if you installed Turbonomic as a new VM image. For more information, see Editing the Turbonomic charts_v1alpha1_xl_cr.yaml file

Using the script interface

If you installed Turbonomic as a VM image, the script to enable embedded reports is already installed on your installation at /opt/local/bin/enable_reporting.py.

Open an SSH terminal session to your Turbonomic instance.

Log in with the System Administrator that you set up when you installed Turbonomic:
- Username: turbo
- Password: [your_private_password]
Go to the script directory.
```
cd /opt/local/bin
```
Run the script.
```
./enable_reporting.py
```
The script prompts you for two passwords:
- Grafana admin password
  
  This password enables access to Grafana from external URLs and also from the extractor component that feeds data to Grafana.
  
  Do not use special characters.
  
  Important:
  This step is the only time that you should change the Grafana Admin password.
- Grafana database password
  
  This password enables communication between Grafana and the PostgreSQL database that stores the reporting data.
After you supply the passwords, the script displays a confirmation message similar to the following example:
```
Succesfully applied new changes to /opt/turbonomic/kubernetes/operator/deploy/crds/charts_v1alpha1_xl_cr.yaml. 
Backup written to /opt/turbonomic/kubernetes/operator/deploy/crds/charts_v1alpha1_xl_cr.yaml.bak
```
This indicates that the script successfully updated the Turbonomic configuration. The script then applies the changed configuration to enable the embedded reports feature. It should display messages similar to the following example:
```
Applying CR file /opt/turbonomic/kubernetes/operator/deploy/crds/charts_v1alpha1_xl_cr.yaml
Warning: kubectl apply should be used on resource created by either 
kubectl create --save-config or kubectl apply
xl.charts.helm.k8s.io/xl-release configured
Waiting for changes to take effect...
Restarting api pod to apply configuration changes.
pod "api-65cf47986f-jxszd" deleted
Changes have been successfully applied. Embedded reporting is now enabled.
```
Verify your installation.
```
./enable_reporting.py --validate
```
If embedded reports are successfully enabled, the script output should be similar to the following example:
```
No obvious embedded reporting installation errors detected.
```

Editing the Turbonomic YAML file

These instructions describe how to locate and edit the charts_v1alpha1_xl_cr.yaml for the VM image installation. If you installed on a Kubernetes node cluster, the Turbonomic configuration file is likely in a different location.

To enable embedded reports, complete the following tasks:

Enable the components that implement the embedded reporting.
Restart the API pod.
Double-check the installation.
Optionally enable email subscriptions.

Enable the Grafana Exporter, TimescaleDB, and data extraction processes by editing the charts_v1alpha1_xl_cr.yaml file.

Open an SSH terminal session to your Turbonomic instance.

Log in with the System Administrator that you set up when you installed Turbonomic:
- Username: turbo
- Password: [your_private_password]

Open the following file in a text editor:

/opt/turbonomic/kubernetes/operator/deploy/crds/charts_v1alpha1_xl_cr.yaml

Specify the IP address of the Turbonomic instance for external access to the embedded reporting database.

In the global: section of the file, add the following line, where <Platform_IP> is the IP address of your instance:
```
global:
  externalTimescaleDBIP: <Platform_IP>
```
If you are using a cloud-based TimescaleDB server, you can alternatively specify your instance by its fully qualified domain name (FQDN):
```
global:
  externalTimescaleDBName: <FQDN>
```
You can also customize port for the TimescaleDB instance by specifying a port value for externalTimescaleDBPort.
```
global:
  externalTimescaleDBName: <FQDN>
  externalTimescaleDBPort: 1143
```
Note: If you intend to use an instance with a custom DB root user, you must also specify the PostgreSQL default root user credentials, as shown in the following example:
```
  properties:
    global:
      dbRootUsername: admin
      dbRootPassword: MyComplexPass
      dbs.postgresDefault:
        rootUserName: postgres
        rootPassword: <The PostgreSQL user's password. The default password in OVA is vmturbo.>
```
Enable the Grafana component.

Find the grafana: section in the crds/charts_v1alpha1_xl_cr.yaml file, and uncomment the line, enabled: true.
Enable postgres as the database type.

Enabling postgres sets persistent storage of historical data for embedded reports. In the grafana: section, find the subsection for grafana.ini: database: and uncomment the line, type: postgres.

The changes that you have made so far should be similar to:
```
global:
    externalTimescaleDBIP: <Platform_IP>
    ...
    
grafana:
    enabled: true
    adminPassword: admin
    grafana.ini:
      database:
        type: postgres
        ...
```
Change the admin and database passwords.

It is good practice to change any passwords, and not keep their default values.

Important:
Use only alpha-numeric characters for these passwords.

These passwords enable communication between the various embedded reports components. Some of the components accept only alpha-numeric characters. If you use special characters, then the components cannot communicate. Further, the steps to correct these passwords require assistance from your Support representative.

To set the passwords:
- Set the Grafana admin password.
  
  This password enables access to Grafana from external URLs and also from the extractor component that feeds data to Grafana. In the grafana: section, change the value of adminPassword.
  
  Do not use special characters.
  
  Assume that your password is MyNewGrafanaPassword. Then, you would set adminPassword: MyNewGrafanaPassword
  
  Important:
  This step is the only time that you should change the Grafana Admin password.
- Set the Grafana database password.
  
  This password enables communication between Grafana and the PostgreSQL database that stores the reporting data. In the grafana: section, find the subsection for grafana.ini: database: password: and change the password value.
```
grafana:
    enabled: true
    adminPassword: MyNewGrafanaPassword
    grafana.ini:
      database:
        type: postgres
        password: MyNewDatabasePassword
```
Enable the reporting processes.

Just after the properties: section that you added, and at the same level to it, add the following entries to enable the reporting processes:
```
  reporting:
    enabled: true
  timescaledb:
    enabled: true
```
It is important that you align these entries with the indentation for the grafana: section and the properties: section. The changes that you have made should now be similar to the following example:
```
global:
    externalTimescaleDBIP: <Platform_IP>
    ...
    
grafana:
    enabled: true
    adminPassword: MyNewGrafanaPassword
    grafana.ini:
      database:
        type: postgres
        password: MyNewDatabasePassword

properties:
    extractor:
        grafanaAdminPassword: MyNewGrafanaPassword
                            
reporting:
    enabled: true
timescaledb:
    enabled: true
```
Note:
The extractor component is enabled by default and no explicit definition is required in your cr.yaml file. However, if the extractor component was manually disabled in your environment previously, you can re-enable it. Search for the following extractor entry in the cr.yaml file:
```
extractor:
  enabled: false
```
Change the entry to true.
When you are done editing the charts_v1alpha1_xl_cr.yaml file, save and apply your changes.
- Save your changes and quit the text editor.
- Run the command to apply the changes.
```
kubectl apply -f /opt/turbonomic/kubernetes/operator/deploy/crds/charts_v1alpha1_xl_cr.yaml
```
- Delete the api pod. If extractor was previously running, delete the extractor pod.
  
  Deleting these pods triggers them to restart, which loads the changes you made.
  
  Run the following command to get the full pod names, run the command,
```
kubectl get pods -n turbonomic
```
  Find the entries for the pods that begin with api and extractor. For example, assume that the entries are:
```
...
api-7887c66f4b-shndq                         1/1     Running   0         
...
extractor-5b86976bc8-vxwz4                   1/1     Running   0         
...
```
  Run the following commands:
```
kubectl delete pod -n turbonomic api-7887c66f4b-shndq
```
```
kubectl delete pod -n turbonomic extractor-5b86976bc8-vxwz4
```

In an SSH terminal session for your Turbonomic instance, set the password for PostgreSQL and enable access to psql on the appliance's local host. Run the following commands:

sudo -iu postgres psql -c "ALTER ROLE postgres WITH PASSWORD 'vmturbo'"

sudo -iu postgres psql -c "CREATE ROLE turbo WITH SUPERUSER CREATEDB CREATEROLE LOGIN REPLICATION BYPASSRLS PASSWORD 'vmturbo'"

Verify your installation.

Verify that the embedded reports pods are running.

kubectl get pods -n turbonomic

The output is similar to the following example:

NAME                                         READY   STATUS    RESTARTS 
extractor-7759dbcb47-vs6hr                   1/1     Running   0         
grafana-84ccb4bfb-l7sp7                      1/1     Running   0

Verify that PostgreSQL is running.

The PostgreSQL database should be running as a daemon on the Turbonomic server machine. To check the status, run the command:

sudo systemctl status postgresql-15.service

In versions prior to Turbonomic 8.14.2, the supported PostgreSQL version was 12.x. If you are using an older version of PostgreSQL, then update to PostgreSQL version 15. For more information, see Upgrade PostgreSQL.

Run the sudo systemctl status postgresql-15.service command.

The output is similar to the following example:

[turbo@upg ~]$ sudo systemctl status postgresql-15.service
● postgresql-15.service - PostgreSQL 15 database server
     Loaded: loaded (/usr/lib/systemd/system/postgresql-15.service; enabled; preset: disabled)
     Active: active (running) since Tue 2024-11-05 12:12:15 EST; 6 days ago
       Docs: https://www.postgresql.org/docs/15/static/
    Process: 61045 ExecStartPre=/usr/pgsql-15/bin/postgresql-15-check-db-dir ${PGDATA} (code=exited, status=0/SUCCESS)
   Main PID: 61050 (postmaster)
      Tasks: 12 (limit: 209714)
     Memory: 1.3G
        CPU: 37min 29.975s
     CGroup: /system.slice/postgresql-15.service
             ├─53565 "postgres: grafana_backend grafana 10.11.12.13(52082) idle"
             ├─61050 /usr/pgsql-15/bin/postmaster -D /var/lib/pgsql/15/data/
             ├─61052 "postgres: logger "
             ├─61053 "postgres: checkpointer "
             ├─61054 "postgres: background writer "
             ├─61056 "postgres: walwriter "
             ├─61057 "postgres: autovacuum launcher "
             ├─61058 "postgres: TimescaleDB Background Worker Launcher "
             ├─61059 "postgres: logical replication launcher "
             ├─61148 "postgres: TimescaleDB Background Worker Scheduler "
             ├─61283 "postgres: TimescaleDB Background Worker Scheduler "
             └─66529 "postgres: grafana_backend grafana 10.11.12.13(50788) idle"

Enabling embedded reporting in Kubernetes and Red Hat OpenShift Container Platform

To enable embedded reporting in a native Kubernetes cluster, such as Azure Kubernetes Service, Amazon Elastic Kubernetes Service, or Red Hat OpenShift, update your Turbonomic charts_v1alpha1_xl_cr.yaml file to create a containerized timescaledb pod that runs the PostgreSQL database.

Note:

In Red Hat OpenShift, Grafana does not accept the global security context. Instead, set the Red Hat OpenShift security context (scc) at the group level. Assuming turbonomic is the project where Turbonomic is deployed, run the following command from the command line in the Red Hat OpenShift cluster:

oc adm policy add-scc-to-group anyuid system:serviceaccounts:turbonomic

If Turbonomic is deployed in a different project or namespace, replace turbonomic with your project or namespace. Although setting scc at the group level is not considered a best practice, this is the only option to enable Grafana in Red Hat OpenShift.

First, enable only the Timescaledb pod to ensure that the reporting database comes up first before you enable any of the other reporting components.

Add the following lines to your Turbonomic charts_v1alpha1_xl_cr.yaml file:
```
  timescaledb:
    enabled: true
  postgresql:
    postgresqlPassword: <your_password>
    persistence:
      size: 500Gi
```
1. Optionally, to set resource requests and limits, add lines similar to the following example to the postgresql section:
```
postgresql:
  persistence:
    size: 500Gi
### Optional to set resource requests and limits
    resources:
      requests:
        memory: 1Gi
```
2. Red Hat OpenShift only: Add the following lines to enable the security context.
```
    volumePermissions:
      enabled: true
```
Apply the updated charts_v1alpha1_xl_cr.yaml file and wait for the timescaledb pod to be ready.
1. Confirm that the timescaledb pod is ready in the user interface (UI) for your container platform or from the command line.
2. Confirm that the PostreSQL database is ready by checking that the logs for the timescaledb pod include a database system is ready to accept connections message.

Next, enable the extractor properties, reporting, and Grafana reporting components.

Add the following lines to your charts_v1alpha1_xl_cr.yaml file:

properties:
  global:
    dbs.postgresDefault:
      rootPassword: <same password as postgresqlPassword field.>
  extractor:
    grafanaAdminPassword: [your_private_password]
grafana:
  adminPassword: [your_private_password]
  enabled: true
  grafana.ini:
    database:
      password: [your_private_password]
      type: postgres
reporting:
  enabled: true

Apply the updated charts_v1alpha1_xl_cr.yaml file.

The following example shows a sample configuration for the Turbonomic charts_v1alpha1_xl_cr.yaml with all the reporting components enabled and the Red Hat OpenShift security context requirements configured. The optional lines to set resource requests and limits are specified in the postgresql section:

#default for OCP apiVersion: charts.helm.k8s.io/v1 kind: Xl metadata:  name: xl-release spec:
#Red Hat OpenShift only
#obtain uid from project, using annotation openshift.io/sa.scc.uid-range or scc.supplemental-groups
#for embedded reporting use this uid as the value for securityContext: in the following sections
securityContext:
  fsGroup: 1000760000
### Red Hat OpenShift only - if needed
nginx:
  nginxIsPrimaryIngress: false
  httpsRedirect: false
### End of Red Hat OpenShift only section ##
properties:
  global:
    dbs.postgresDefault:
      rootPassword: <same password as postgresqlPassword field.>
  extractor:
    grafanaAdminPassword: [your_private_password]
grafana:
  adminPassword: [your_private_password]
  enabled: true
  grafana.ini:
    database:
      password: [your_private_password]
      type: postgres
reporting:
  enabled: true
timescaledb:
  enabled: true
postgresql:
  postgresqlPassword: <your_password>
  persistence:
    size: 500Gi
### Optional to set resource requests and limits
    resources:
      requests:
        memory: 1Gi
### End of optional section
### Red Hat OpenShift only
  securityContext:
    runAsUser: 1000760000
  volumePermissions:
    enabled: true
    securityContext:
      runAsUser: 1000760000

To enable the Embedded Reporting link in the Turbonomic UI, delete the API pod.

From your container platform UI or the command line, find the pod that begins with api-, for example api-7887c66f4b-shndq, and delete it.

Run the following command to get the full pod names, run the command,
```
kubectl get pods -n turbonomic
```
Find the pod that begins with api. For example, assume that the entry is:
```
...
api-7887c66f4b-shndq                         1/1     Running   0         
...
```
Run the following command:
```
kubectl delete pod -n turbonomic api-7887c66f4b-shndq
```
In the Turbonomic UI, click Reports in the main navigation menu.

You are redirected to the Grafana reports UI.