promtail

Deploy and configure Grafana's Promtail

25,817 downloads

14,721 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 2.1.0 (latest)
  • 2.0.0
  • 1.0.0
  • 0.4.0 (deleted)
  • 0.3.1
  • 0.3.0
  • 0.2.0
released Aug 31st 2021
This version is compatible with:
  • Puppet Enterprise 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x
  • Puppet >= 6.1.0 < 8.0.0
  • , , , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'grafana-promtail', '2.1.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add grafana-promtail
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install grafana-promtail --version 2.1.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

grafana/promtail — version 2.1.0 Aug 31st 2021

Reference

Table of Contents

Classes

Public Classes

  • promtail: promtail's main interface. All interactions should be with this class.

Private Classes

  • promtail::config: Creates files and folders associated with promtail's config
  • promtail::install: Installs promtail
  • promtail::service: Creates a service defintion for promtail

Functions

Classes

promtail

promtail's main interface. All interactions should be with this class. The promtail module is intended to install and configure Grafana's promtail tool for shipping logs to Loki.

Examples

include promtail
Sample of defining within a profile
class { 'promtail':
  clients_config_hash   => $clients_config_hash,
  positions_config_hash => $positions_config_hash,
  scrape_configs_hash   => $_real_scrape_configs_hash,
  password_file_content => $sensitive_password_file_content,
  password_file_path    => $password_file_path,
  service_ensure        => $service_ensure,
  server_config_hash    => $server_config_hash,
  target_config_hash    => $target_config_hash,
  bin_dir               => $bin_dir,
  checksum              => $checksum,
  version               => $version,
}
Settings in a Hiera file
---
promtail::password_file_path: '/etc/promtail/.gc_pw'
promtail::password_file_content: ENC[PKCS7,MIIBasdfasdfasdfasdfasdfasdf==]
promtail::server_config_hash:
  server:
    http_listen_port: 9274
    grpc_listen_port: 0
promtail::clients_config_hash:
  clients:
    - url: 'https://logs-us-west1.grafana.net/api/prom/push'
      basic_auth:
        username: '1234'
        password_file: '/etc/promtail/.gc_pw'
promtail::positions_config_hash:
  positions:
    filename: /tmp/positions.yaml
promtail::scrape_configs_hash:
  scrape_configs:
    - job_name: journal
      journal:
        max_age: 12h
        labels:
          job: systemd-journal
          host: "%{facts.networking.fqdn}"
      relabel_configs:
        - source_labels:
            - '__journal__systemd_unit'
          target_label: 'unit'
        - source_labels:
            - 'unit'
          regex: "session-(.*)"
          action: replace
          replacement: 'pam-session'
          target_label: 'unit'
Merging scrape configs in Hiera
class profile::logging::promtail {
  $_real_scrape_configs_hash = lookup('promtail_scrape_configs_hash', {merge => 'deep'})
  class { 'promtail':
    scrape_configs_hash => $_real_scrape_configs_hash,
  }
}

Parameters

The following parameters are available in the promtail class:

service_enable

Data type: Boolean

The value passed to the service resource's enable parameter for promtail's service

service_ensure

Data type: Enum['running', 'stopped']

The value passed to the service resource's ensure parameter for promtail's service

clients_config_hash

Data type: Hash

Describes how Promtail connects to multiple instances of Loki, sending logs to each. See https://github.com/grafana/loki/blob/master/docs/clients/promtail/configuration.md for all parameters.

positions_config_hash

Data type: Hash

Describes how to save read file offsets to disk. See https://github.com/grafana/loki/blob/master/docs/clients/promtail/configuration.md for all parameters.

scrape_configs_hash

Data type: Hash

Each scrape_config block configures how Promtail can scrape logs from a series of targets using a specified discovery method. See https://github.com/grafana/loki/blob/master/docs/clients/promtail/configuration.md for all parameters.

bin_dir

Data type: Stdlib::Absolutepath

The directory in which to create a symlink to the promtail binary

checksum

Data type: String[1]

The checksum of the promtail binary. Note: each platform has its own checksum. Values can be found with each release on GitHub

version

Data type: String[1]

The version as listed on the GitHub release page See https://github.com/grafana/loki/releases for a list

server_config_hash

Data type: Optional[Hash]

Configures Promtail's behavior as an HTTP server. Defaults will be used if this block is omitted. See https://github.com/grafana/loki/blob/master/docs/clients/promtail/configuration.md for all parameters.

Default value: undef

target_config_hash

Data type: Optional[Hash]

Configures how tailed targets will be watched. Defaults will be used if this block is omitted. See https://github.com/grafana/loki/blob/master/docs/clients/promtail/configuration.md for all parameters.

Default value: undef

password_file_path

Data type: Optional[Stdlib::Absolutepath]

The fully qualified path to the file containing the password used for basic auth

Default value: undef

password_file_content

Data type: Optional[Sensitive[String[1]]]

The value to be placed in the password file. This value is cast to Sensitive via lookup_options defined in data/common.yaml

Default value: undef

source_url

Data type: Stdlib::HTTPUrl

The URL from which promtail packages can be downloaded

Default value: 'https://github.com/grafana/loki/releases/download'

Functions

promtail::strip_yaml_header

Type: Ruby 4.x API

A function to strip the --- from the beginning of a string

Examples

concat::fragment { 'server_config_hash':
  target  => $config_file,
  content => $promtail::server_config_hash.promtail::to_yaml.promtail::strip_yaml_header,
  order   => '10',
}

promtail::strip_yaml_header(String $yaml_string)

A function to strip the --- from the beginning of a string

Returns: String Returns the string with the leading header stripped off

Examples
concat::fragment { 'server_config_hash':
  target  => $config_file,
  content => $promtail::server_config_hash.promtail::to_yaml.promtail::strip_yaml_header,
  order   => '10',
}
yaml_string

Data type: String

A string that may start with the ---'s used to denote a YAML file

promtail::to_yaml

Type: Ruby 4.x API

A function to convert a hash into yaml for the promtail config

Examples

promtail::to_yaml($promtail::config_hash)

promtail::to_yaml(Hash $config_hash)

A function to convert a hash into yaml for the promtail config

Returns: String Returns the YAML version of the hash as a string

Examples
promtail::to_yaml($promtail::config_hash)
config_hash

Data type: Hash

A Puppet hash to be converted into YAML