Documentation Grafana Enterprise Metrics Set up Set up the GEM plugin for Grafana

Set up the GEM plugin for Grafana

Requirements

Grafana Enterprise 9.5 or higher.

Refer to Deploy Grafana Enterprise on Kubernetes if you are using Kubernetes. Otherwise, refer to Install Grafana for more information.

Install the plugin in your GEM instance

There are multiple ways to install the plugin to your local Grafana Enterprise instance. For more information, refer to Grafana Enterprise Metrics app installation.

Enable and configure the plugin

1. Log in to your Grafana Enterprise Metrics.
2. Go to the Config/Plugins page and select the Grafana Enterprise Metrics plugin from list.
3. From the configuration page of the plugin, enable the plugin by clicking on the Enable plugin button.
4. Provide the necessary API settings so that the plugin can connect to your cluster:

• Access Token: Enter the admin-scoped access token that you generated when setting up your GEM cluster.

• Enterprise Metrics URL: Enter the URL of your GEM cluster. For single-process clusters, this is any node in the cluster. For microservice deployments, this URL is the GEM gateway.

1. Click Save API settings.
2. Verify that the plugin loads and can communicate with the GEM admin API endpoints.
3. Navigate to the Grafana Enterprise Metrics plugin through the main menu to see the default access policy under the Access policies tab.

Configure the plugin via provisioning

You can alternatively manage the GEM plugin via a plugin config.

Example GEM plugin configuration file

yaml Copy

apiVersion: 1

apps:
  # <string> the type of app, plugin identifier. Required
  - type: grafana-metrics-enterprise-app
    # <int> Org ID. Default to 1, unless org_name is specified
    org_id: 1
    # <string> Org name. Overrides org_id unless org_id not specified
    org_name: Main Org.
    # <bool> disable the app. Default to false.
    disabled: false
    # <map> fields that will be converted to json and stored in jsonData.
    jsonData:
      # key/value pairs of string to object
      backendUrl: 'URL'
      base64EncodedAccessTokenSet: true
    # <map> fields that will be converted to json, encrypted and stored in secureJsonData. 
    secureJsonData:
      # <string> a base64 encoding of $USER:$TOKEN
      base64EncodedAccessToken: OmV4YW1wbGVUb2tlbkZvckJhc2U2NEVuY29kZWRBY2Nlc3NUb2tlbgo=

The format of the base64EncodedAccessToken token is a base64-encoded representation of a user-token pair, separated by colon. For example, $USER:$TOKEN. If you’ve set your GEM token as the TOKEN environment variable, and you’ve also set a USER environment variable, then you can generate a compatible base64EncodedAccessToken token in the following format:

sh Copy

USER=
TOKEN=exampleTokenForBase64EncodedAccessToken
echo $USER:$TOKEN | base64

To denote an admin user, you can leave the user portion of the pair as an empty string. For example:

Legacy base64EncodedAccessToken field

Prior to version 6.0.0 of the plugin, a base64EncodedAccessToken field was required for authentication. This has been replaced with the simpler accessToken.

The following is provided for troubleshooting purposes, or for users of versions earlier than 6.0.0.

Moving forward, use accessToken in your configuration.

If both base64EncodedAccessToken and accessToken are present in the jsonData, the base64EncodedAccessToken is ignored in versions 6.0.0 and later.

The format of the base64EncodedAccessToken token is a base64-encoded representation of a user-token pair, separated by colon. For example, $USER:$TOKEN. If you’ve set your GEM token as the TOKEN environment variable, and you’ve also set a USER environment variable, then you can generate a compatible base64EncodedAccessToken token in the following format:

sh Copy

#USER INTENTIONALLY LEFT BLANK, INDICATING THE "ADMIN" USER
USER=
TOKEN=exampleTokenForBase64EncodedAccessToken
echo $USER:$TOKEN | tr -d '[:space:]' | base64 -w0

Though $USER is typically blank, you can opt to leave it in the expression to ensure that the : character is present. The following is a more direct way of obtaining the same result:

sh Copy

echo :$TOKEN | tr -d '[:space:]' | base64 -w0

These examples both result in the following base64EncodedAccessToken string:

Copy

OmV4YW1wbGVUb2tlbkZvckJhc2U2NEVuY29kZWRBY2Nlc3NUb2tlbgo=

You can apply the encoded token string to the configuration under secureJsonData:

yaml Copy

secureJsonData:
  # <string> a base64 encoding of $USER:$TOKEN
  base64EncodedAccessToken: OmV4YW1wbGVUb2tlbkZvckJhc2U2NEVuY29kZWRBY2Nlc3NUb2tlbgo=

Next steps

Now that you have correctly configured the plugin, you can move on to setting up a GEM tenant and visualizing your data.

Install dashboards

Install dashboards to add the latest versions of the cardinality and self-monitoring dashboards to your GEM instance. These dashboards help you to gain additional insight into your data in GEM.

1. In your Grafana instance, go to Administration > Plugins and data > Plugins > Grafana Enterprise Metrics.
2. Select the Dashboards tab.
3. Select Install Cardinality dashboards, Install Self-monitoring dashboards, or both, depending on which dashboards you want to install.

The Installed dashboards list updates to show the dashboards you installed. To view a dashboard, select it from the list. To reinstall the dashboards following an update, repeat the same steps.

Configure a private certificate authority

If you are running GEM in a closed environment using a self-signed certificate, you need to configure a private certificate authority. For more information, refer to Configure a Private CA (Certificate Authority) in the Grafana documentation.

Limitations

The GEM plugin for Grafana allows to manage only 1 GEM cluster, and it doesn’t support managing multiple GEM clusters with a single GEM plugin installation. In case you need to manage multiple GEM clusters you should configure 1 GEM cluster per Grafana organization.