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

This is an Ansible role to run the Telegraf Agent with the Docker input plugin inside a Docker container.

Table of Contents

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

Background

Telegraf is a tool used to collect metrics for InfluxDB. Both use the Go programming language, which can be challenging to package for traditional Linux systems like Debian. Therefore, using Docker to run them is convenient.

The Telegraf Docker Input Plugin collects metrics from running Docker containers using the Docker Engine API. Running the Telegraf agent in a Docker container requires access to the Docker endpoint on the host, usually through a UNIX socket. For security reasons, it is advisable to run the agent as a non-privileged user. This means you must have a user on the Docker host that belongs to the docker group to access the Docker API from inside the container.

This project sets up everything you need, including the user and the container, in one Ansible role.

Requirements

Containers are managed using the community.docker.docker_container module from the community.docker collection. You may already have it, but if you don’t, check the module's documentation to install it.

Install

You can install this role through your requirements.yml file either from Ansible Galaxy or from the Git repository.

Role Variables

Mandatory Variables

• tdid_influxdb_org:
  • Description: The name of the InfluxDB organization.
• tdid_influx_token:
  • Description: The InfluxDB API token. It is recommended to keep this token secure, using vault or secure lookup.

Optional Variables

• tdid_conf_dir:
  • Default: "/etc"
  • Description: The directory on the host where the configuration file will be copied.
• tdid_docker_image:
  • Default: "telegraf:latest"
  • Description: Name of the Docker image to use (combination of "telegraf" and a tag). The default is the latest image from Docker Hub.
• tdid_influxdb_url:
  • Default: "http://localhost:8086"
  • Description: The URL of the InfluxDB server.
• tdid_influxdb_bucket:
  • Default: "default"
  • Description: The bucket to write data into.
• tdid_timezone:
  • Default: "UTC"
  • Description: Timezone for the Telegraf container (TZ environment variable).
• tdid_user:
  • Default: "telegraf"
  • Description: The system user created on the host. It needs to be part of the Docker group to access the Docker API.

Dependencies

No other Ansible roles are used, only the community module mentioned above.

Example Playbook

To use this role, include it in your playbook 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

Contributions and pull requests are welcome.

License

This project is licensed under the MIT License unless stated otherwise and complies with REUSE standards.

© 2022 Alexander Dahl and contributors

Author Information

Written by Alexander Dahl for Netz39 infrastructure monitoring.