InfluxDB Role

Overview

This role installs and configures InfluxDB 1.x time-series database on RedHat-based systems. It adds the official InfluxData repository, installs InfluxDB, configures HTTP/UDP/logging settings, creates databases with users and grants privileges, sets up retention policies for data lifecycle management, and ensures the service is enabled and started. The role is fully idempotent and checks for existing resources before creating them.

Purpose

Time-Series Database: Store and query time-stamped data (metrics, events, analytics)
Automated Installation: Install InfluxDB from official repository
Database Management: Create databases, users, and retention policies
Configuration: HTTP API, UDP input, logging customization
Privilege Management: Grant database-specific permissions to users
Data Retention: Automatic data expiration policies
Monitoring Integration: Backend for Telegraf/Grafana stack
Idempotent: Safe to run multiple times without errors

Requirements

Ansible 2.9 or higher
RedHat-based system (RHEL, CentOS, Rocky Linux, AlmaLinux)
Internet access to repos.influxdata.com
Proper sudo/root permissions
Port 8086 available for HTTP API
Optional: Port for UDP input if enabled

What is InfluxDB?

InfluxDB is an open-source time-series database optimized for:

Fast, high-availability storage of time-stamped data
Metrics collection from servers, applications, sensors
Real-time analytics and monitoring
Downsampling and data retention policies
InfluxQL query language (SQL-like)
Integration with Telegraf (metrics collection), Grafana (visualization)

Use cases:

Server monitoring (CPU, memory, disk)
Application metrics (response times, error rates)
IoT sensor data
Network monitoring
Business analytics

Role Variables

Optional Variables

Variable	Default	Description
`influxdb_version`	`1`	InfluxDB major version (1.x)
`influxdb_repo_baseurl`	Auto-detected	Repository URL
`influxdb_gpg_key`	Official URL	GPG key for package verification
`influxdb_service_name`	`influxdb`	Systemd service name
`influxdb_service_enabled`	`true`	Enable service on boot
`influxdb_service_state`	`started`	Desired service state
`influxdb_config_path`	`/etc/influxdb/influxdb.conf`	Configuration file path
`influxdb_databases`	`[]`	List of databases to create
`influxdb_http_enabled`	`""` (default)	Enable HTTP API
`influxdb_http_bind_address`	`""` (default)	HTTP bind address
`influxdb_udp_enabled`	`""` (disabled)	Enable UDP input
`influxdb_logging_level`	`""` (default)	Log level

Variable Details

influxdb_databases

List of databases to create with users, privileges, and retention policies.

Structure:

influxdb_databases:
  - name: database_name
    user: username
    password: "{{ vault_password }}"
    retention_policy:
      name: policy_name
      duration: 30d
      replication: 1
      default: true

Complete example:

influxdb_databases:
  - name: homelab
    user: telegraf
    password: "{{ vault_influxdb_telegraf_password }}"
    retention_policy:
      name: thirty_days
      duration: 30d
      replication: 1
      default: true

  - name: monitoring
    user: grafana
    password: "{{ vault_influxdb_grafana_password }}"
    retention_policy:
      name: one_year
      duration: 365d
      replication: 1
      default: true

  - name: shortterm
    user: telegraf
    password: "{{ vault_influxdb_telegraf_password }}"
    retention_policy:
      name: seven_days
      duration: 7d
      replication: 1
      default: true

Field descriptions:

Field	Required	Description
`name`	Yes	Database name
`user`	No	Username to create and grant privileges
`password`	No	User password (use vault variable)
`retention_policy`	No	Data retention configuration

Retention Policy fields:

Field	Required	Description
`name`	Yes	Policy name
`duration`	Yes	How long to keep data (e.g., `7d`, `30d`, `52w`, `INF` for infinite)
`replication`	Yes	Replication factor (1 for single node)
`default`	No	Make this the default policy (default: false)

HTTP Configuration

influxdb_http_enabled: true
influxdb_http_bind_address: ":8086"
influxdb_http_log_enabled: true
influxdb_http_access_log_path: "/var/log/influxdb/access.log"

Note: Empty string ("") uses InfluxDB defaults.

UDP Configuration

influxdb_udp_enabled: true
influxdb_udp_bind_address: ":8089"
influxdb_udp_database: "udp_data"

Use case: High-throughput write scenarios (statsd, collectd)

Logging Configuration

influxdb_logging_format: "logfmt"  # or "json"
influxdb_logging_level: "info"     # error, warn, info, debug
influxdb_logging_suppress_logo: true

Dependencies

This role has no dependencies on other Ansible roles.

Example Playbook

Basic Usage

---
- name: Install InfluxDB
  hosts: influxdb
  become: true

  vars:
    influxdb_databases:
      - name: homelab
        user: telegraf
        password: "{{ vault_influxdb_telegraf_password }}"

  roles:
    - influxdb

With Retention Policies

---
- name: Install InfluxDB with Retention Policies
  hosts: influxdb
  become: true

  vars:
    influxdb_databases:
      - name: metrics
        user: telegraf
        password: "{{ vault_influxdb_telegraf_password }}"
        retention_policy:
          name: thirty_days
          duration: 30d
          replication: 1
          default: true

      - name: logs
        user: logstash
        password: "{{ vault_influxdb_logstash_password }}"
        retention_policy:
          name: seven_days
          duration: 7d
          replication: 1
          default: true

  roles:
    - influxdb

With Custom HTTP Configuration

---
- name: Install InfluxDB with Custom HTTP Settings
  hosts: influxdb
  become: true

  vars:
    influxdb_http_bind_address: "192.168.x.x:8086"
    influxdb_http_log_enabled: true
    influxdb_logging_level: "warn"

    influxdb_databases:
      - name: production
        user: app_writer
        password: "{{ vault_influxdb_app_password }}"

  roles:
    - influxdb

With UDP Input

---
- name: Install InfluxDB with UDP Input
  hosts: influxdb
  become: true

  vars:
    influxdb_udp_enabled: true
    influxdb_udp_bind_address: ":8089"
    influxdb_udp_database: "statsd"

    influxdb_databases:
      - name: statsd
        retention_policy:
          name: one_week
          duration: 7d
          replication: 1
          default: true

  roles:
    - influxdb

What This Role Does

Adds InfluxData repository
- URL: https://repos.influxdata.com/rhel/
- Enables GPG verification
Installs InfluxDB package via dnf/yum
- Version 1.x from official repository
Configures HTTP API in /etc/influxdb/influxdb.conf:
- Bind address
- Access logging
- Enables/disables HTTP endpoint
Configures logging:
- Format (logfmt or json)
- Level (error, warn, info, debug)
- Logo suppression
Configures UDP input (if enabled):
- Bind address
- Default database for UDP writes
Starts and enables service:
- systemctl start influxdb
- systemctl enable influxdb
Waits for InfluxDB to be ready (port 8086)
Checks existing users (idempotent):
- Queries: SHOW USERS
- Parses JSON response
Creates users:
- Only creates if not exists
- Uses passwords from vault
Checks existing databases (idempotent):
- Queries: SHOW DATABASES
- Parses JSON response
Creates databases:
- Only creates if not exists
Grants privileges:
- GRANT ALL ON database TO user
Checks existing retention policies:
- Queries: SHOW RETENTION POLICIES ON database
Creates retention policies:
- Only creates if not exists
- Sets as default if specified

InfluxDB CLI Commands

The role uses the influx CLI for database management:

User Management

# Show users
influx -execute "SHOW USERS"

# Create user
influx -execute "CREATE USER username WITH PASSWORD 'password'"

# Grant privileges
influx -execute "GRANT ALL ON database_name TO username"

Database Management

# Show databases
influx -execute "SHOW DATABASES"

# Create database
influx -execute "CREATE DATABASE database_name"

# Drop database
influx -execute "DROP DATABASE database_name"

Retention Policy Management

# Show retention policies
influx -execute "SHOW RETENTION POLICIES ON database_name"

# Create retention policy
influx -execute "CREATE RETENTION POLICY thirty_days ON database_name DURATION 30d REPLICATION 1 DEFAULT"

# Alter retention policy
influx -execute "ALTER RETENTION POLICY thirty_days ON database_name DURATION 60d"

Retention Policies Explained

What is a Retention Policy?

A retention policy (RP) defines:

How long InfluxDB keeps data
How many copies to maintain (replication factor)
Whether it’s the default policy for new writes

Duration Examples

Duration	Description
`7d`	7 days
`4w`	4 weeks
`30d`	30 days
`52w`	52 weeks (1 year)
`365d`	365 days
`INF`	Infinite (never delete)

Replication Factor

1: Single copy (typical for single-node deployments)
2+: Multiple copies (for high availability clusters)

Default Policy

Each database must have a default retention policy:

Used when no policy specified in write
Created automatically if not defined (default: autogen with infinite duration)

Example Scenario

High-resolution recent data, low-resolution historical:

influxdb_databases:
  - name: metrics
    retention_policy:
      name: detailed
      duration: 7d
      replication: 1
      default: true  # New writes go here

  # Later, create downsampled data with longer retention
  # Using continuous query (not managed by this role)

Idempotency

The role is fully idempotent:

Users: Checks if user exists before creating
Databases: Checks if database exists before creating
Retention Policies: Checks if policy exists before creating
Privileges: Grants are idempotent (no error if already granted)

Safe to run multiple times without:

Creating duplicate resources
Generating errors for existing resources
Changing existing configurations unnecessarily

Configuration File

The role modifies /etc/influxdb/influxdb.conf:

[http]
# ANSIBLE MANAGED HTTP CONFIG
enabled = true
bind-address = ":8086"
log-enabled = true
access-log-path = "/var/log/influxdb/access.log"
# ANSIBLE MANAGED HTTP CONFIG

[logging]
# ANSIBLE MANAGED LOGGING CONFIG
format = "logfmt"
level = "info"
suppress-logo = true
# ANSIBLE MANAGED LOGGING CONFIG

[[udp]]
# ANSIBLE MANAGED UDP CONFIG
enabled = true
bind-address = ":8089"
database = "udp_data"
# ANSIBLE MANAGED UDP CONFIG

Note: Role uses blockinfile with markers for clean updates.

Service Management

# Check status
systemctl status influxdb

# Start service
systemctl start influxdb

# Stop service
systemctl stop influxdb

# Restart service
systemctl restart influxdb

# View logs
journalctl -u influxdb -f

# Check version
influx -version

InfluxDB Data Locations

Type	Path
Data	`/var/lib/influxdb/data/`
WAL	`/var/lib/influxdb/wal/`
Meta	`/var/lib/influxdb/meta/`
Config	`/etc/influxdb/influxdb.conf`
Logs	`/var/log/influxdb/`

Security Considerations

No Authentication by Default: InfluxDB 1.x has no authentication by default
Network Access: Restrict port 8086 to trusted networks
User Passwords: Stored in Ansible Vault with no_log: true
Privilege Grants: Users granted full privileges on their databases only
Configuration Backups: Role doesn’t backup config before changes
Consider HTTPS: Use reverse proxy (nginx) for HTTPS access

Enable Authentication (Manual)

Authentication is not managed by this role. To enable:

# Edit config
vi /etc/influxdb/influxdb.conf

# Add to [http] section:
auth-enabled = true

# Restart service
systemctl restart influxdb

# Create admin user (if not exists)
influx -execute "CREATE USER admin WITH PASSWORD 'admin_password' WITH ALL PRIVILEGES"

# Use authentication in CLI
influx -username admin -password 'admin_password'

Firewall Configuration

InfluxDB uses these ports:

Port	Protocol	Purpose
8086	TCP	HTTP API
8089	UDP	UDP input (if enabled)

# Open HTTP API port
firewall-cmd --permanent --add-port=8086/tcp
firewall-cmd --reload

# Open UDP port (if enabled)
firewall-cmd --permanent --add-port=8089/udp
firewall-cmd --reload

Notes

Role installs InfluxDB 1.x (not 2.x)
InfluxDB 1.x uses InfluxQL query language
Default port: 8086 (HTTP API)
No authentication enabled by default
Retention policies automatically delete old data
Role is idempotent and checks for existing resources
UDP input is optional (high-throughput scenarios)
Configuration uses blockinfile (preserves non-managed settings)

Troubleshooting

”Failed to download metadata for repo ‘influxdb’”

Cause: Network connectivity or repository issue

Solution:

# Test repository access
curl -I https://repos.influxdata.com/rhel/9/x86_64/stable/

# Check DNS
nslookup repos.influxdata.com

# Verify GPG key
curl https://repos.influxdata.com/influxdata-archive.key

# Clear dnf cache
dnf clean all

“Connection refused” when accessing InfluxDB

Cause: Service not running or firewall blocking

Solution:

# Check service
systemctl status influxdb

# Start if stopped
systemctl start influxdb

# Check if listening
netstat -tlnp | grep 8086

# Check firewall
firewall-cmd --list-ports
firewall-cmd --add-port=8086/tcp --permanent
firewall-cmd --reload

“Database already exists” error

Should not happen - role is idempotent.

If it occurs:

# Check existing databases
influx -execute "SHOW DATABASES"

# Role should detect and skip creation

“User already exists” error

Should not happen - role checks before creating.

If it occurs:

# Check existing users
influx -execute "SHOW USERS"

# Verify user exists

Retention policy not deleting data

Cause: Retention enforcement runs periodically

Check:

# Verify policy exists
influx -execute "SHOW RETENTION POLICIES ON database_name"

# Check shard duration (data actually deleted when shard expires)
# Shards typically 1 hour to 7 days depending on retention

# Force retention policy enforcement (manual)
influx -execute "DROP SHARD <shard_id>" -database database_name

High memory usage

Cause: Large queries, many series, or insufficient retention

Solution:

Implement retention policies (automatic cleanup)
Reduce query complexity
Increase server memory
Use continuous queries for downsampling

Disk space filling up

Cause: No retention policies or long duration

Solution:

# Check disk usage
du -sh /var/lib/influxdb/

# Implement retention policies
influx -execute "CREATE RETENTION POLICY seven_days ON database_name DURATION 7d REPLICATION 1 DEFAULT"

# Drop old shards manually if needed
influx -execute "SHOW SHARDS" -database database_name
influx -execute "DROP SHARD <shard_id>" -database database_name

Testing After Installation

Verify Service Running

# Check service active
systemctl is-active influxdb
# Should output: active

# Check service enabled
systemctl is-enabled influxdb
# Should output: enabled

# Check port listening
netstat -tlnp | grep 8086
# Should show influxd listening

Test HTTP API

# Test API endpoint
curl -I http://localhost:8086/ping

# Should return: HTTP/1.1 204 No Content

# Check InfluxDB version
curl http://localhost:8086/ping
# Returns X-Influxdb-Version header

Verify Databases Created

# List databases
influx -execute "SHOW DATABASES"

# Should show your configured databases

Verify Users Created

# List users
influx -execute "SHOW USERS"

# Should show users with privileges

Test Write and Query

# Write data point
influx -execute 'INSERT cpu,host=server01 value=0.64'

# Query data
influx -execute 'SELECT * FROM cpu' -database database_name

# Should return the data point

Verify Retention Policy

# Show retention policies
influx -execute "SHOW RETENTION POLICIES ON database_name"

# Should show your configured policies

Performance Considerations

Memory: 2-4 GB recommended for production
CPU: 2+ cores for concurrent queries
Disk: SSD strongly recommended (high IOPS for WAL)
Network: Low latency important for distributed setups
Shard Duration: Shorter = more files, longer = larger memory usage

Optimization Tips

Use retention policies: Automatic data cleanup
Index appropriately: Cardinality matters (avoid high-cardinality tags)
Batch writes: More efficient than individual writes
Continuous queries: Pre-aggregate data for faster queries
Monitor shard count: Too many shards = performance issues

Best Practices

Use retention policies for all databases (prevent unbounded growth)
Store passwords in Ansible Vault (never plaintext)
Restrict network access to port 8086
Enable authentication for production (manual step, not in role)
Regular backups of /var/lib/influxdb/
Monitor disk space (implement alerts)
Use SSD storage for better performance
Tag appropriately: Low cardinality tags, high cardinality fields
Batch writes: More efficient than single points
Test queries: Optimize before production

Backup and Restore

Backup InfluxDB

# Backup all databases
influxd backup -portable /backup/influxdb/$(date +%Y%m%d)

# Backup specific database
influxd backup -portable -database database_name /backup/influxdb/database_name

Restore InfluxDB

# Restore all databases
influxd restore -portable /backup/influxdb/20260107/

# Restore specific database
influxd restore -portable -database database_name /backup/influxdb/database_name/

This role is often used with:

telegraf_agent: Send metrics to InfluxDB
grafana_install: Visualize InfluxDB data
grafana_datasource_create: Configure InfluxDB as Grafana datasource
deploy_system_monitoring: Monitor hosts, send data via Telegraf

Upgrading InfluxDB

Check Current Version

influx -version
# Or: influxd version

Upgrade Process

# Backup first (important!)
influxd backup -portable /backup/influxdb-pre-upgrade

# Update package
dnf update influxdb

# Restart service
systemctl restart influxdb

# Verify version
influx -version

Note: Review release notes for breaking changes between versions.

License

MIT

Author

Created for homelab infrastructure management.

Influxdb

InfluxDB Role

Overview

Purpose

Requirements

What is InfluxDB?

Role Variables

Optional Variables

Variable Details

influxdb_databases

HTTP Configuration

UDP Configuration

Logging Configuration

Dependencies

Example Playbook

Basic Usage

With Retention Policies

With Custom HTTP Configuration

With UDP Input

What This Role Does

InfluxDB CLI Commands

User Management

Database Management

Retention Policy Management

Retention Policies Explained

What is a Retention Policy?

Duration Examples

Replication Factor

Default Policy

Example Scenario

Idempotency

Configuration File

Service Management

InfluxDB Data Locations

Security Considerations

Enable Authentication (Manual)

Firewall Configuration

Tags

Notes

Troubleshooting

”Failed to download metadata for repo ‘influxdb’”

“Connection refused” when accessing InfluxDB

“Database already exists” error

“User already exists” error

Retention policy not deleting data

High memory usage

Disk space filling up

Testing After Installation

Verify Service Running

Test HTTP API

Verify Databases Created

Verify Users Created

Test Write and Query

Verify Retention Policy

Performance Considerations

Optimization Tips

Best Practices

Backup and Restore

Backup InfluxDB

Restore InfluxDB

Related Roles

Upgrading InfluxDB

Check Current Version

Upgrade Process

License

Author