DEBOPS.INFLUXDB(5)

NAME
debops.influxdb - Manage InfluxDB service using Ansible

SYNOPSIS

debops service/influxdb [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

InfluxDB <https://en.wikipedia.org/wiki/InfluxDB> is an open-source time series database (TSDB) developed by InfluxData. It is written in Go and optimized for fast, high-availability storage and retrieval of time series data in fields such as operations monitoring, application metrics, Internet of Things sensor data, and real-time analytics. Ansible roles debops.influxdb and debops.influxdb_server allow you to manage a InfluxDB server and / or access it remotely from other hosts.

The debops.influxdb role is the "client" part - it uses Ansible delegation to configure users and databases in local or remote InfluxDB servers. You can use debops.influxdb_server role to manage the InfluxDB server itself.

GETTING STARTED

debops.influxdb role is only the "client" part. To have a working InfluxDB installation, you also need to setup the debops.influxdb_server role somewhere. It can be either on the same host, or on a separate host. See the debops.influxdb_server documentation to learn how to install the database server itself.

  Local database server

If the database server is installed locally, it will be automatically detected and used by the debops.influxdb role without any additional configuration. Also, if a remote server was used previously, and a local one was installed, it will automatically override the remote configuration. You might need to recreate the databases and user accounts in that case.

  Remote database server

If your InfluxDB server is configured on a remote host and you don't have a local installation, debops.influxdb will detect that and won't manage the databases/user accounts without a server specified. To point it to a server, you need to set a variable in the inventory:

influxdb__server: 'influxdb.example.org'

This needs to be a FQDN address of a host with InfluxDB server installed. DNS name is required because this access is via a HTTP(S) API. Currently only 1 server at a time is supported by the role.

If debops.pki role is used to configure a PKI environment, with default domain PKI realm enabled, debops.influxdb_server role will configure the provided private keys and X.509 certificates to enable TLS connections to the database by default.

If the PKI environment is not configured or disabled, connections to the database server will be performed in cleartext, so you might want to consider securing them by configuring server on a separate internal network, or accessing it over a VPN connection. You can use debops.subnetwork, debops.tinc and debops.dnsmasq Ansible roles to set up a VPN internal network to secure communication between hosts.

  Example inventory

To enable InfluxDB client support on a host, you need to add that host to [debops_service_influxdb] Ansible group:

[debops_service_influxdb]
hostname

When InfluxDB server is properly configured, or installed locally, you can create user accounts and databases using inventory variables:

influxdb__databases:
  - name: 'application_production'
influxdb__users:
  - name: 'application'
    grants:
       - database: 'application_production'
         privilege: 'ALL'

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.influxdb role:

---
- name: Manage InfluxDB client
  collections: [ 'debops.debops' ]
  hosts: [ 'debops_service_influxdb' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: python
      tags: [ 'role::python', 'skip::python', 'role::influxdb' ]
      python__dependent_packages3:
        - '{{ influxdb__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ influxdb__python__dependent_packages2 }}'
    - role: influxdb
      tags: [ 'role::influxdb', 'skip::influxdb' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::influxdb
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

DEFAULT VARIABLE DETAILS

Some of debops.influxdb default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  influxdb__databases

List of databases that should be present or absent on a given InfluxDB server. Each database is defined as a YAML dict with the following keys:

database or name
    Required. Name of the database. Names of databases can contain any unicode character

state
    Optional. If value is present, the database will be created; if absent, the database will be removed. It is defaulted to present.

proxies
    Optional. Defaults to {{ omit }}. Dict of HTTP(S) proxy to use for Requests to connect to InfluxDB server. Overrides influxdb__proxies.

validate_certs
    Optional, boolean. Defaults to True. If set to False, the SSL certificates will not be validated. This should only set to no used on personally controlled sites using self-signed certificates. Overrides influxdb__validate_certs.

  Examples

Create databases, remove some of the existing ones:

influxdb__databases:
  - name: 'dbname'

  influxdb__retention_policies

List of retention policies that should be present on a given InfluxDB server database. Each retention policy is defined as a YAML dict with the following keys:

policy or name
    Required. Name of the retention policy.

database
    Required. Name of the database. Names of databases can contain any unicode character

duration
    Required. Determines how long InfluxDB keeps the data. The duration is a duration literal or INF (infinite). The minimum duration for a retention policy is one hour and the maximum duration is INF.

replication
    Required. Determines how many independent copies of each point are stored in the cluster. If the replication factor is set to 2, each series is stored on 2 separate nodes. If the replication factor is equal to the number of data nodes, data is replicated on each node in the cluster.

default
    Optional. Defaults to False. Sets the new retention policy as the default retention policy for the database.

proxies
    Optional. Defaults to {{ omit }}. Dict of HTTP(S) proxy to use for Requests to connect to InfluxDB server. Overrides influxdb__proxies.

validate_certs
    Optional, boolean. Defaults to True. If set to False, the SSL certificates will not be validated. This should only set to no used on personally controlled sites using self-signed certificates. Overrides influxdb__validate_certs.

  Examples

Create retention policies:

influxdb__retention_policies:
  - name: 'fourweeks'
    database: 'dbname'
    duration: '4w'
    replication: 1
    default: True

  influxdb__users

List of user accounts that should be present or absent on a given InfluxdDB server. Each user account is defined as a dict with a set of keys and values.

  User account parameters

user or name
    Required. Name of the user.

password
    Optional. If specified, the role will set it as the password for the InfluxDB account. If not present, a random password will be generated automatically and stored in the secret/ directory on the Ansible Controller. Refer to the debops.secret role for more details.

grants
    Optional. Privileges to grant to this user. Takes a list of dicts containing the database and privilege keys. If this argument is not provided, the current grants will be left alone. If an empty list is provided, all grants for the user will be removed. It is added in Ansible 2.8.

admin
    Optional. Whether the user should be in the admin role or not. Since Ansible 2.8, the role will also be updated. It is defaulted to no.

state
    Optional. If value is present, the database will be created; if absent, the database will be removed. It is defaulted to present.

proxies
    Optional. Defaults to {{ omit }}. Dict of HTTP(S) proxy to use for Requests to connect to InfluxDB server. Overrides influxdb__proxies.

validate_certs
    Optional, boolean. Defaults to True. If set to False, the SSL certificates will not be validated. This should only set to no used on personally controlled sites using self-signed certificates. Overrides influxdb__validate_certs.

  Examples

Create an user

influxdb__users:
  - name: 'someuser'
    grants:
      - database: 'dbname'
        privilege: 'READ'

AUTHOR
Pedro Luis Lopez

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others