Telegraf Docker in Docker (telegraf-docker-in-docker)

Ansible Role for running Telegraf Agent with Docker input plugin in Docker container.

Table of Contents

• Background
• Requirements
• Install
• Role Variables
• Dependencies
• Example Playbook
• Contributing
• License
• Author Information

Background

Telegraf is an agent often used to feed metrics into InfluxDB. Both are written in the Go language, which is hard to package for traditional distributions like Debian GNU/Linux, so running those in Docker is convenient.

The Telegraf Docker Input Plugin gathers metrics on running docker containers from the Docker Engine API. Running that Telegraf agent in a Docker container itself requires access to the Docker endpoint on the host, usually a UNIX socket. From a security point of view it makes sense to run the agent as unpriviledged user, which makes it necessary to have some user on the docker host system being in the docker group, which can be used from inside the container to access that endpoint.

This project does all the setup of that user and the container in one ansible role.

Requirements

Containers are setup with the community.docker.docker_container module, which is part of the community.docker collection. You might already have it installed. If not follow the modules documentation on how to install it.

Install

This role can be installed through your requirements.yml, either from Ansible Galaxy or through the Git repo.

Role Variables

Mandatory Variables

• tdid_influxdb_org:
  • Description: InfluxDB organization name.
• tdid_influx_token:
  • Description: InfluxDB API token. Recommended to not put this into the playbook, but use vault or secure lookup!

Optional Variables

• tdid_conf_dir:
  • Default: "/etc"
  • Description: The destination directory on the host, where the role copies the configuration file to.
• tdid_docker_image:
  • Default: "telegraf:latest"
  • Description: Combination of "telegraf" and some tag. Default uses the latest image from Docker Hub.
  • Examples:
    • "telegraf:latest"
    • "telegraf:alpine"
    • "telegraf:1.23"
    • "telegraf:1.24-alpine"
• tdid_influxdb_url:
  • Default: "http://localhost:8086"
  • Description: URL of the node running InfluxDB node.
• tdid_influxdb_bucket:
  • Default: "default"
  • Description: Destination bucket to write into.
• tdid_timezone:
  • Default: "UTC"
  • Description: Environment variable TZ passed to the telegraf container.
  • Examples:
    • Europe/Berlin
    • Asia/Nepal
• tdid_user:
  • Default: "telegraf"
  • Description: System user created or modified on the host.
  • Background: Mapping arbitrary host users to container users is not easily possible. Access rights on the host apply to the same numerical UIDs and GIDs inside of containers. A process inside of a container accessing something on the host must run with the uid/gid required on the host to access certain things on the host. It is necessary to have a user in the docker group to access the docker engine api endpoint without super user permissions. If not present on the host already, this user will be created as a system user, and put into the group 'docker'. The Telegraf agent can run inside the container with that UID.

Dependencies

No other galaxy roles used, just the community module listed above.

Example Playbook

Just include the role and set some variables.

Minimal Example

- hosts: servers
  roles:
    - role: telegraf_docker_in_docker
      vars:
        tdid_influxdb_org: Home
        tdid_influx_token: "{{ lookup( … ) }}"

Full Example

- hosts: servers
  roles:
    - role: telegraf_docker_in_docker
      vars:
        tdid_influxdb_org: Home
        tdid_influx_token: "{{ lookup( … ) }}"
        tdid_conf_dir: "/etc/telegraf"
        tdid_influxdb_bucket: devops
        tdid_influxdb_url: "http://influx.example.org:8086"
        tdid_docker_image: telegraf:1.24-alpine
        tdid_timezone: "Europe/Berlin"
        tdid_user: telegraf

Contributing

Pull requests accepted.

License

This project is licensed unter the MIT License unless noted differently in the file and adheres to REUSE compliance.

© 2022 Alexander Dahl and contributors

Author Information

Written by Alexander Dahl for Netz39 infrastructure monitoring.