InfluxDB Role¶

Overview¶

InfluxDB is a time-series database optimized for storing and querying metrics data. The solti-monitoring collection uses InfluxDB v2 OSS for metrics storage. This role deploys InfluxDB as a Podman container, providing a robust solution for collecting, storing, and analyzing time-series data from Telegraf collectors and serving as a backend for Grafana dashboards.

Important: InfluxDB v2 OSS does NOT support S3 object storage. Use NFS mounts for shared/scalable storage.

Requirements¶

Ansible 2.9+
Target system with Podman and Systemd.
An NFS server (for NFS-Backed Deployment).

Installation / Quick Start¶

The influxdb role deploys InfluxDB as a Podman container (consumed from solti-containers) using systemd quadlets.

Basic Deployment (Local Storage)¶

- hosts: monitoring_servers
  become: true
  roles:
    - role: jackaltx.solti_containers.podman  # Provides container runtime
    - role: jackaltx.solti_monitoring.influxdb
      vars:
        influxdb_admin_token: "{{ vault_influxdb_token }}" # Store in Ansible Vault
        influxdb_org: "example-org"
        influxdb_bucket: "telegraf"
        influxdb_data_path: "/var/lib/influxdb2"

NFS-Backed Deployment (Production)¶

- hosts: monitoring_servers
  become: true
  tasks:
    # Mount NFS first
    - name: Mount NFS volume
      ansible.posix.mount:
        src: "nas.example.com:/export/influxdb"
        path: "/mnt/nfs/influxdb"
        fstype: nfs
        opts: "rw,sync"
        state: mounted
  roles:
    - role: jackaltx.solti_containers.podman
    - role: jackaltx.solti_monitoring.influxdb
      vars:
        influxdb_admin_token: "{{ vault_influxdb_token }}"
        influxdb_org: "example-org"
        influxdb_bucket: "telegraf"
        influxdb_data_path: "/mnt/nfs/influxdb"
        influxdb_retention: "30d"

Role Variables / Configuration¶

Basic Configuration¶

Name	Description	Default
`influxdb_version`	The InfluxDB version to deploy.	`2.7`
`influxdb_port`	The HTTP API port for InfluxDB.	`8086`
`influxdb_admin_user`	The admin username for InfluxDB.	`admin`
`influxdb_admin_token`	The admin API token (store in Ansible Vault).	`""`
`influxdb_org`	The organization name for InfluxDB.	`example-org`
`influxdb_bucket`	The default bucket for metrics.	`telegraf`
`influxdb_retention`	The data retention period.	`30d`

Storage Options¶

Name	Description	Default
`influxdb_data_path`	The path for storing InfluxDB data. For production, consider using an NFS mount.	`/var/lib/influxdb2`

Container Configuration¶

Name	Description	Default
`influxdb_container_name`	The name for the InfluxDB container.	`influxdb`
`influxdb_image`	The Docker image for InfluxDB.	`docker.io/influxdb:2.7`
`influxdb_restart_policy`	The container restart policy.	`always`

Usage¶

Health Check¶

Verify InfluxDB is running:

curl -I http://localhost:8086/health

API Access¶

All API requests require token authentication. Additional tokens for Telegraf clients can be created via the influx CLI (inside the container) or through the InfluxDB API.

Query API¶

Query metrics using Flux:

curl -X POST http://localhost:8086/api/v2/query \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/vnd.flux" \
  -d 'from(bucket: "telegraf")
    |> range(start: -1h)
    |> filter(fn: (r) => r["_measurement"] == "cpu")'

Service Management¶

InfluxDB runs as a Podman container managed by systemd.

# Check status
systemctl status influxdb

# Start/stop/restart
systemctl start influxdb
systemctl stop influxdb
systemctl restart influxdb

# View logs
journalctl -u influxdb -f

# Check container
podman ps | grep influxdb

Troubleshooting¶

Check Container Status¶

podman ps -a | grep influxdb
podman logs influxdb --tail 100

Check Service Status¶

systemctl status influxdb
journalctl -u influxdb -n 100 --no-pager

Verify API Access¶

Health check: curl -I http://localhost:8086/health
Ping endpoint: curl http://localhost:8086/api/v2/ping

Common Issues¶

Container won't start: Check podman logs influxdb, verify data path permissions/existence, and NFS mount status.
API not accessible: Verify port 8086 is open, check firewall, and container running status.
Authentication errors: Verify token correctness and permissions.
Out of disk space: Check disk usage, reduce retention, or delete old buckets.
High memory usage: Reduce cache sizes, add more RAM, or optimize queries.
NFS mount issues: Verify NFS server reachability, mount status, and NFS write access.

Role-Specific Sections¶

Retention Policies¶

Retention policies can be set when creating or updating buckets.

Resource Requirements¶

Minimum requirements are 2 CPU cores and 2GB RAM. Sizing guidance is provided for small, medium, and large deployments, with NFS mounts recommended for scalability and backup.

Backup and Recovery¶

NFS Snapshot Backup: For NFS storage, leverage NFS server snapshots for backup.
Manual Export/Import: InfluxDB CLI tools can be used for manual export and import of data.
Disaster Recovery with NFS: Simple recovery by mounting the same NFS volume to a new instance.

Performance Tuning¶

Cache settings and compaction configurations can be adjusted for performance optimization.

Monitoring InfluxDB¶

InfluxDB exposes Prometheus-format metrics at /metrics, allowing self-monitoring via Telegraf.

Security Considerations¶

Store tokens securely in Ansible Vault.
Restrict network access to port 8086 and use WireGuard for remote collectors.
Consider using TLS/SSL or a reverse proxy.
Run as a rootless Podman container with limited capabilities.

Container Integration¶

This role integrates with the solti-containers collection to provide the Podman runtime and generates systemd quadlet files for container lifecycle management.