Grafana is a multi-platform open source analytics and interactive visualization web application.

In this post we’ll look at how to quickly install Grafana with an NGINX reverse proxy over HTTPS using Puppet Bolt.

Initialize a New Bolt Project

Ensure that the latest version of Puppet Bolt is installed before getting started.

Puppet Bolt utilizes Project directories as launching points for running Bolt operations. In this post we’ll create a Bolt project for deploying Grafana. The following command will create a directory named dashboard in the current working directory and install the grafana, nginx and openssl forge module along with the necessary module dependencies.

bolt project init dashboard --modules puppet-grafana,puppet-nginx,camptocamp-openssl

The command should generate output similar to that shown below if it ran successfully.

Successfully created Bolt project at /system/path/dashboard
Successfully created Puppetfile at /system/path/dashboard/Puppetfile
Successfully synced modules from /system/path/dashboard/Puppetfile to /system/path/dashboard/modules
Successfully installed puppet-grafana, puppet-nginx, camptocamp-openssl

There should now be a bolt.yaml file in the dashboard directory. In the dashboard project directory create a file named bolt-project.yaml with the following content.

# bolt-project.yaml
name: dashboard

Deploy Grafana

With the modules installed all we need to do now is instantiate the module by creating a Bolt plan to run.

Create a Dashboard Install Plan

Create a plans directory in the project directory.

mkdir plans

Create a plan named install.pp in the plans directory with the following content. The following plan preps the remote system with a Puppet agent, generates a self-signed SSL certificate, installs Grafana and Nginx as a reverse proxy with the SSL certificate. The plan includes a number of hiera lookups that reference data or settings that we will specify later in this post.

plan dashboard::install(
  TargetSpec $targets,
  Integer $grafana_port = 3000,
  Integer $grafana_secure_port = 443,
 ) {
  $targets.apply_prep
  apply($targets) {
    openssl::certificate::x509 { "${lookup('dashboard::install::grafana_domain_name')}":
      country => lookup('dashboard::install::ssl_cert_country'),
      organization => lookup('dashboard::install::ssl_cert_org'),
      locality => lookup('dashboard::install::ssl_cert_locality'),
      state => lookup('dashboard::install::ssl_cert_state'),
      commonname => lookup('dashboard::install::grafana_domain_name'),
      owner => 'nginx',
      group => 'nginx',
      days => lookup('dashboard::install::ssl_cert_expiration'),
    }
    include nginx
    nginx::resource::server { "${lookup('dashboard::install::grafana_domain_name')}":
      listen_port => $grafana_secure_port,
      ssl_port => $grafana_secure_port,
      ssl => true,
      ssl_cert => "/etc/ssl/certs/${lookup('dashboard::install::grafana_domain_name')}.crt",
      ssl_key => "/etc/ssl/certs/${lookup('dashboard::install::grafana_domain_name')}.key",
      proxy => "http://localhost:${grafana_port}",
    }
    class { 'grafana':
      cfg => {
        app_mode => 'production',
        server => {
          http_port => $grafana_port,
          domain => lookup('dashboard::install::grafana_domain_name'),
        },
        users => {
          allow_sign_up => false,
        },
      }
    }
  }
}

We can now verify that Bolt recognizes our new plan by running the following command that lists registered Bolt plans.

bolt plan show

If the plan registers properly the output should include a dashboard::install entry.

aggregate::count
aggregate::nodes
aggregate::targets
canary
**dashboard::install**  
facts
facts::info
puppetdb_fact
reboot
terraform::apply
terraform::destroy

Setup Hiera

Hiera is a built-in key-value configuration data lookup system. This allows us to use a robust lookup system for defining parameters in our Bolt code. In addition to yaml files we can use external systems such as a CMDB to provide data to our Bolt code.

Create a hiera.yaml file in the dashboard directory with the content below. The hiera configuration defines where and how to find the values for the install plan.

--------
version: 5
defaults:
  datadir: data
hierarchy:
  - name: "Per-node data"
    path: "nodes/%{facts.networking.fqdn}.yaml"
  - name: "Common data"
    path: "common.yaml"

Create a directory named data to store our hiera data files as specified in the hiera configuration file.

mkdir data

Create a file named common.yaml in the data directory. This hiera data file defines settings that will be common across deployments of Grafana in our environment.

--------
dashboard::install::ssl_cert_country: "US"
dashboard::install::ssl_cert_state: "IL"
dashboard::install::ssl_cert_locality: "Chicago"
dashboard::install::ssl_cert_org: "Green Reed Technology"
dashboard::install::ssl_cert_expiration: 365

Create a directory named nodes in the data directory we created earlier. This directory will be where we place node specific hiera data.

mkdir nodes

Create a file with the name of the target node’s FQDN ending in .yaml (grafana01.grt.local.yaml in this example) in the nodes directory created in the previous step. The file should include an entry for the dashboard::install::grafana_domain_name which is the domain name that the Grafana dashboard will be accessed with.

--------
dashboard::install::grafana_domain_name: "dashboard.grt.local"

Run Dashboard Install Plan

With the plan registered and hiera configured we are ready to run the plan by running the following command.

bolt plan run dashboard::install --targets grafana01.grt.local --no-host-key-check --user root

If the plan ran successfully it should have generated output similar to that displayed below.

bolt plan run dashboard::install --targets grafana01.grt.local --no-host-key-check --user root
Project-level configuration in bolt.yaml is deprecated if using bolt-project.yaml. Transport config should be set in inventory.yaml, all other config should be set in bolt-project.yaml.
Starting: plan dashboard::install
Starting: install puppet and gather facts on grafana01.grt.local
Finished: install puppet and gather facts with 0 failures in 76.28 sec
Starting: apply catalog on grafana01.grt.local
Finished: apply catalog with 0 failures in 32.75 sec
Finished: plan dashboard::install in 1 min, 49 sec
Plan completed successfully with no result

If our plan ran successfully we should now be able to browse to the Grafana dashboard in a web browser at https://${grafana_domain_name} if the hostname is associated with the ip address of the node.

Once you login successfully you will be prompted to change the default Grafana password.

You should now be presented with the Grafana dashboard after successfully changing the Grafana default password.

We have now successfully installed Grafana using Puppet Bolt. The Grafana puppet module includes a plethora of other settings that can be defined to easily deploy a fully configured Grafana instance in minutes. The Puppet Forge has a large number of existing content that can be utilized to quickly get started with a number of other platforms.