Installation

This guide will walk you through installing Opni Monitoring and adding clusters to the system. Before proceeding, please read the section on Terminology to familiarize yourself with a few key terms.

Prerequisites

Infrastructure

One main cluster where the Opni Monitoring control-plane components will be installed. The main cluster must be accessible to all downstream clusters.
One or more downstream clusters which will be configured to send metrics to the main cluster
A domain name or subdomain at which to host the Opni Gateway public API. For a demo or testing installation, you can use sslip.io. In the rest of this guide, the domain name will be referred to as <gateway_address>.
All clusters must have a default storage class available.

Dependencies

helm version 3.8 or later
helm-diff plugin, which can be installed with the following command:
```
$ helm plugin install https://github.com/databus23/helm-diff
```
helmfile, which can be installed using your distribution’s package manager or from the GitHub release page.

Setting up the main cluster

First, clone the opni-monitoring repo:

$ git clone https://github.com/rancher/opni-monitoring

Ensure you are running helm version 3.8 or later:

$ helm version
version.BuildInfo{Version:"v3.8.1", GitCommit:"5cb9af4b1b271d11d7a97a71df3ac337dd94ad37", GitTreeState:"clean", GoVersion:"go1.17.8"}

Chart configuration

Inside the opni-monitoring repo, there are a few template yaml files in deploy/custom which you will need to copy and edit before continuing. These files will be used to configure authentication and Cortex long-term storage.

1. Authentication

For a demo or testing installation, follow the instructions in the Demo Auth section.
For a production installation, follow the instructions in the OpenID Connect section.

2. Cortex

For a demo or testing installation, you can create an empty deploy/custom/cortex.yaml file to use the default configuration.
For a production installation, edit deploy/custom/cortex.yaml using the template as reference and the Cortex docs.

Chart Installation

Inside the opni-monitoring repo, change directories to deploy/.

Ensure your current kubeconfig points to the main cluster.
Run helmfile apply
Wait for all resources to become ready. This may take a few minutes.

DNS Configuration

Identify the external IP of the opni-monitoring load balancer.
Configure A records such that <gateway_address> and grafana.<gateway_address> both resolve to the IP address of the load balancer (skip this step if you are using sslip.io or a similar service).

Accessing the dashboard

Once all the pods in the opni-monitoring namespace are running, open the web dashboard:

Port-forward to the opni-monitoring-internal service:

kubectl -n opni-monitoring port-forward svc/opni-monitoring-internal management-web:management-web

Open your browser to http://localhost:12080.

Next Steps

This section is optional, but highly recommended.

Adding a cluster

First, let’s add the main cluster itself - this allows us to gather metrics from the Opni Gateway and Cortex. Follow these steps to add the cluster to Opni Monitoring:

Create a token

Tokens are used to authenticate new clusters during the bootstrap process. To create one:

Navigate to the Tokens tab in the sidebar
Click Create Token
Use the default fields, and click Create. The new token will appear in the table.

Token Expiration

All tokens will expire after a certain amount of time. The default value is 10 minutes, but you can choose any duration you like. If your token expires, you can simply create a new one.

Add a cluster

Navigate to the Clusters tab in the sidebar
Click Add Cluster
In the Capabilities drop-down menu, select metrics
In the Token drop-down menu, select the token we just created. When a capability and token have been selected, an install command will appear below.
Check the box that says Install Prometheus Operator (however, if you already have Prometheus Operator installed on a cluster you want to add, leave it unchecked).
Click on the install command to copy it to the clipboard
In a terminal, ensure your KUBECONFIG environment variable or ~/.kube/config context points to the cluster you want to add (in this case, the main cluster), then paste and run the command.
In a few seconds, you should see a green banner informing you that the cluster has been added. If you want to add any additional clusters right now, you can repeat step 7 for each cluster using the same command you copied previously.
Click Finish to return to the cluster list.