Set up the Grafana Enterprise Logs plugin for Grafana

Requirements

Grafana Enterprise 7.3.0 or higher.

If you are using Kubernetes, refer to Deploy Grafana Enterprise on Kubernetes. Otherwise, refer to Install Grafana.

Install the plugin in your GEL instance

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

Enable and configure the plugin

Log in to your Grafana Enterprise Logs.
Go to the Config/Plugins page and select the Grafana Enterprise Logs (GEL) plugin from list.
From the configuration page of the plugin, enable the plugin by clicking on the “Enable plugin” button.
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 GEL cluster.
Grafana Enterprise Logs URL: Enter the URL of your GEL cluster. For single-process clusters, this is any node in the cluster. For microservice deployments, the URL is the GEL gateway.
Configuration GEL plugin page

Click Save API settings.
Verify that the plugin loads and can communicate with the GEL admin API endpoints.
Navigate to the GEL 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 GEL plugin via a plugin configuration file.

Example GEL plugin configuration file

apiVersion: 1

apps:
  # <string> the type of app, plugin identifier. Required
  - type: grafana-enterprise-logs-app
    # <integer> 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.
    # <boolean> 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: http://[...]
    # <map> fields that will be converted to json, encrypted and stored in secureJsonData. 
    secureJsonData:
      # <string> 
      accessToken: [...]

Optional `policiesOnly` field

For a simpler user experience that only shows the “Access policies” page, you can include the following in the jsonData configuration:

jsonData:
  policiesOnly: true

This simpler mode of operation only gives users access to the ability to create access policies and tokens. It requires setting up the environment to include at least one tenant.

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 a colon. For example, $USER:$TOKEN. If you’ve set your GEL 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:

#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:

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

These examples both result in the following base64EncodedAccessToken string:

OmV4YW1wbGVUb2tlbkZvckJhc2U2NEVuY29kZWRBY2Nlc3NUb2tlbgo=

You can apply the encoded token string to the configuration under secureJsonData in your plugin configuration file:

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

Next steps

Now that you have correctly configured the GEL app plugin, follow directions in Set up a GEL tenant and visualize your data.

Limitations

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