Deploying Grafana on Enclave

Grafana is an open-source platform for analytics and monitoring. It’s an ideal choice to use in combination with an InfluxDB Metric Drain.

Here’s what makes Grafana so compelling:

  • It makes it easy to build beautiful graphs and set up alerts.
  • It works out of the box with InfluxDB.
  • It works very well in a containerized environment like Enclave.

Here’s how you can deploy Grafana on Enclave:

Provisioning a Postgres Database

Grafana needs a database to store sessions and Dashboard definitions. It works great with PostgreSQL, which you can deploy on Enclave. The rest of this tutorial assumes that you provisioned a PostgreSQL Database and have access to its credentials.

Configuring the Database

Once you created the PostgreSQL Database, create a tunnel using the aptible db:tunnel command, then connect using psql and run the following commands to create a sessions database for use by Grafana:

CREATE DATABASE sessions;

Then, connect to the newly-created sessions database:

\c sessions;

And, finally, create a table for Grafana to store sessions in:

CREATE TABLE session (
        key       CHAR(16) NOT NULL,
        data      BYTEA,
        expiry    INTEGER NOT NULL,
        PRIMARY KEY (key)
);

Deploying the Grafana App

Grafana is available as a Docker image and can be configured using environment variables. As a result, you can use Direct Docker Image Deploy to easily deploy Grafana on Enclave.

Here’s a minimal deployment configuration to get you started. In the example below, you’ll have to substitute a number of variables:

  • $ADMIN_PASSWORD: Generate a strong password for your Grafana admin user.
  • $SECRET_KEY: Generate a random string (40 characters will do).
  • $YOUR_DOMAIN: The domain name you intend to use to connect to Grafana (e.g. grafana.example.com).
  • $DB_USERNAME: The username for your PostgreSQL Database. For a PostgreSQL Database on Enclave, this will be aptible.
  • $DB_PASSWORD: The password for your PostgreSQL Database.
  • $DB_HOST: The host for your PostgreSQL Database.
  • $DB_PORT: The port for your PostgreSQL Database.
aptible apps:create grafana

aptible deploy --app grafana --docker-image grafana/grafana \
        "GF_SECURITY_ADMIN_PASSWORD=$ADMIN_PASSWORD" \
        "GF_SECURITY_SECRET_KEY=$SECRET_KEY" \
        "GF_DEFAULT_INSTANCE_NAME=aptible" \
        "GF_SERVER_ROOT_URL=https://$YOUR_DOMAIN" \
        "GF_SESSION_PROVIDER=postgres" \
        "GF_SESSION_PROVIDER_CONFIG=user=$DB_USERNAME password=$DB_PASSWORD host=$DB_HOST port=$DB_PORT dbname=sessions sslmode=require" \
        "GF_LOG_MODE=console" \
        "GF_DATABASE_TYPE=postgres" \
        "GF_DATABASE_HOST=$DB_HOST:$DB_PORT" \
        "GF_DATABASE_NAME=db" \
        "GF_DATABASE_USER=$DB_USERNAME" \
        "GF_DATABASE_PASSWORD=$DB_PASSWORD" \
        "GF_DATABASE_SSL_MODE=require" \
        "FORCE_SSL=true"

Tip

There are a lot more configuration options available in Grafana. Review Grafana’s configuration documentation for more information.

Expose Grafana

Finally, follow the How do I expose my web app on the Internet? tutorial to expose your Grafana app over the internet.

Make sure to use the same domain you configured Grafana with ($YOUR_DOMAIN in the example above)!

Next Steps

Logging in

Once you’ve exposed Grafana, you can navigate to $YOUR_DOMAIN to access Grafana. Connect using the username admin and the password you configured above (ADMIN_PASSWORD).

Connecting to an InfluxDB Database

Once logged in to Grafana, you can connect Grafana to an InfluxDB Database by creating a new data source. To do so, click the Grafana icon in the top left, then navigate to data sources and click “Add data source”.

The following assumes you have provisioned an InfluxDB Database. You’ll need to interpolate the following values

  • $INFLUXDB_HOST: The hostname for your InfluxDB Database. This is of the form db-$STACK-$ID.aptible.in.
  • $INFLUXDB_PORT: The port for your InfluxDB Database.
  • $INFLUXDB_USERNAME: The username for your InfluxDB Database. Typically aptible.
  • $INFLUXDB_PASSWORD: The password.

These parameters are represented by the connection URL for your InfluxDB database in the Aptible Dashboard and CLI. For example, if your connection URL is https://foo:bar@db-qux-123.aptible.in:456, then the parameters are:

  • $INFLUXDB_HOST: db-qux-123.
  • $INFLUXDB_PORT: 456
  • $INFLUXDB_USERNAME: foo
  • $INFLUXDB_PASSWORD: bar

Once you have those parameters, in Grafana, use the following configuration for your data source:

  • Name: Any name of your choosing. This will be used to reference this data source in the Grafana Web UI.
  • Type: InfluxDB
  • HTTP settings:
    • URL: https://$INFLUXDB_HOST:$INFLUXDB_PORT.
    • Access: proxy
  • HTTP Auth: Leave everything unchecked
  • Skip TLS Verification: Do not select
  • InfluxDB Details:
    • Database: If you provisioned this InfluxDB Database on Enclave and / or are using it for a InfluxDB Database Metric Drain, set this to db. Otherwise, use the database of your choice.
    • User: $INFLUXDB_USERNAME
    • Password: $INFLUXDB_PASSWORD

Finally, save your changes.

If you are using an InfluxDB Metric Drain, consider reviewing Suggested Queries.

Grafana documentation

Once you’ve added your first data source, you might also want to consider following Grafana’s getting started documentation to familiarize yourself with Grafana.

Tip

If you get an error connecting, use the aptible logs commands to troubleshoot.

That said, an error logging in is very likely due to not properly creating the sessions database and the session table in it as indicated in Configuring the Database.