diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c954cd..556cd6b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,11 +1,32 @@ -# Changelog +# Change log -All notable changes to this project will be documented in this file. +All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org). -## Release 0.1.0 +## [v0.2.0](https://github.com/puppetlabs/influxdb/tree/v0.2.0) (2022-03-01) -**Features** +[Full Changelog](https://github.com/puppetlabs/influxdb/compare/v0.1.0...v0.2.0) -**Bugfixes** +### Added -**Known Issues** +- Use a mixin module instead of inheritance [\#7](https://github.com/puppetlabs/influxdb/pull/7) ([m0dular](https://github.com/m0dular)) +- Add puppet-strings documentation [\#1](https://github.com/puppetlabs/influxdb/pull/1) ([m0dular](https://github.com/m0dular)) + +### Fixed + +- Fix fqdn in install error message [\#3](https://github.com/puppetlabs/influxdb/pull/3) ([m0dular](https://github.com/m0dular)) + +## [v0.1.0](https://github.com/puppetlabs/influxdb/tree/v0.1.0) (2021-12-13) + +[Full Changelog](https://github.com/puppetlabs/influxdb/compare/v0.0.2...v0.1.0) + +## [v0.0.2](https://github.com/puppetlabs/influxdb/tree/v0.0.2) (2021-11-18) + +[Full Changelog](https://github.com/puppetlabs/influxdb/compare/v0.0.1...v0.0.2) + +## [v0.0.1](https://github.com/puppetlabs/influxdb/tree/v0.0.1) (2021-11-16) + +[Full Changelog](https://github.com/puppetlabs/influxdb/compare/ee8ed1c47240e3712966f9e651749528a5235160...v0.0.1) + + + +\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)* diff --git a/REFERENCE.md b/REFERENCE.md new file mode 100644 index 0000000..d72b094 --- /dev/null +++ b/REFERENCE.md @@ -0,0 +1,967 @@ +# Reference + + + +## Table of Contents + +### Classes + +* [`influxdb::install`](#influxdbinstall): Installs, configures, and performs initial setup of InfluxDB 2.x +* [`influxdb::profile::toml`](#influxdbprofiletoml): Installs the toml-rb gem inside Puppet server + +### Resource types + +* [`influxdb_auth`](#influxdb_auth): Manages authentication tokens in InfluxDB +* [`influxdb_bucket`](#influxdb_bucket): Manages InfluxDB buckets +* [`influxdb_dbrp`](#influxdb_dbrp): Manages dbrps, or database and retention policy mappings. These provide backwards compatibilty for 1.x queries. Note that these are automatically created by the influxdb_bucket resource, so it isn't necessary to use this resource unless you need to customize them. +* [`influxdb_label`](#influxdb_label): Manages labels in InfluxDB +* [`influxdb_org`](#influxdb_org): Manages organizations in InfluxDB +* [`influxdb_setup`](#influxdb_setup): Manages initial setup of InfluxDB. It is recommended to use the influxdb::install class instead of this resource directly. +* [`influxdb_user`](#influxdb_user): Manages users in InfluxDB. Note that currently, passwords can only be set upon creating the user and must be updated manually using the cli. A user must be added to an organization to be able to log in. + +### Functions + +* [`influxdb::from_toml`](#influxdbfrom_toml) +* [`influxdb::hosts_with_pe_profile`](#influxdbhosts_with_pe_profile) +* [`influxdb::retrieve_token`](#influxdbretrieve_token) +* [`influxdb::to_toml`](#influxdbto_toml) + +## Classes + +### `influxdb::install` + +Installs, configures, and performs initial setup of InfluxDB 2.x + +#### Examples + +##### Basic usage + +```puppet +include influxdb::install + +class {'influxdb::install': + initial_org => 'my_org', + initial_bucket => 'my_bucket', +} +``` + +#### Parameters + +The following parameters are available in the `influxdb::install` class: + +* [`manage_repo`](#manage_repo) +* [`manage_setup`](#manage_setup) +* [`repo_name`](#repo_name) +* [`version`](#version) +* [`archive_source`](#archive_source) +* [`use_ssl`](#use_ssl) +* [`manage_ssl`](#manage_ssl) +* [`ssl_cert_file`](#ssl_cert_file) +* [`ssl_key_file`](#ssl_key_file) +* [`ssl_ca_file`](#ssl_ca_file) +* [`influxdb_host`](#influxdb_host) +* [`intial_org`](#intial_org) +* [`intial_bucket`](#intial_bucket) +* [`admin_user`](#admin_user) +* [`admin_pass`](#admin_pass) +* [`token_file`](#token_file) +* [`initial_org`](#initial_org) +* [`initial_bucket`](#initial_bucket) + +##### `manage_repo` + +Data type: `Boolean` + +Whether to manage a repository to provide InfluxDB packages. Defaults to true + +Default value: ``true`` + +##### `manage_setup` + +Data type: `Boolean` + +Whether to perform initial setup of InfluxDB. This will create an initial organization, bucket, and admin token. Defaults to true. + +Default value: ``true`` + +##### `repo_name` + +Data type: `String` + +Name of the InfluxDB repository if using $manage_repo. Defaults to influxdb2 + +Default value: `'influxdb2'` + +##### `version` + +Data type: `String` + +Version of InfluxDB to install. Changing this is not recommended. + +Default value: `'2.1.1'` + +##### `archive_source` + +Data type: `String` + +URL containing an InfluxDB archive if not installing from a repository. Defaults to version 2-2.1.1 on amd64 architechture. + +Default value: `'https://dl.influxdata.com/influxdb/releases/influxdb2-2.1.1-linux-amd64.tar.gz'` + +##### `use_ssl` + +Data type: `Boolean` + +Whether to use http or https connections. Defaults to true (https). + +Default value: ``true`` + +##### `manage_ssl` + +Data type: `Boolean` + +Whether to manage the SSL bundle for https connections. Defaults to true. + +Default value: ``true`` + +##### `ssl_cert_file` + +Data type: `String` + +SSL certificate to be used by the influxdb service. Defaults to the agent certificate issued by the Puppet CA for the local machine. + +Default value: `"/etc/puppetlabs/puppet/ssl/certs/${trusted['certname']}.pem"` + +##### `ssl_key_file` + +Data type: `String` + +Private key used in the CSR for the certificate specified by $ssl_cert_file. +Defaults to the private key of the local machine for generating a CSR for the Puppet CA + +Default value: `"/etc/puppetlabs/puppet/ssl/private_keys/${trusted['certname']}.pem"` + +##### `ssl_ca_file` + +Data type: `String` + +CA certificate issued by the CA which signed the certificate specified by $ssl_cert_file. Defaults to the Puppet CA. + +Default value: `'/etc/puppetlabs/puppet/ssl/certs/ca.pem'` + +##### `influxdb_host` + +Data type: `String` + +fqdn of the host running InfluxDB. Defaults to the fqdn of the local machine + +Default value: `$facts['fqdn']` + +##### `intial_org` + +Name of the initial organization to use during initial setup. Defaults to puppetlabs + +##### `intial_bucket` + +Name of the initial bucket to use during initial setup. Defaults to puppet_data + +##### `admin_user` + +Data type: `String` + +Name of the administrative user to use during initial setup. Defaults to admin + +Default value: `'admin'` + +##### `admin_pass` + +Data type: `Sensitive[String[1]]` + +Password for the administrative user in Sensitive format used during initial setup. Defaults to puppetlabs + +Default value: `Sensitive('puppetlabs')` + +##### `token_file` + +Data type: `String` + +File on disk containing an administrative token. This class will write the token generated as part of initial setup to this file. +Note that functions or code run in Puppet server will not be able to use this file, so setting $token after setup is recommended. + +Default value: `$facts['identity']['user']` + +##### `initial_org` + +Data type: `String` + + + +Default value: `'puppetlabs'` + +##### `initial_bucket` + +Data type: `String` + + + +Default value: `'puppet_data'` + +### `influxdb::profile::toml` + +Installs the toml-rb gem inside Puppet server + +#### Examples + +##### Basic usage + +```puppet +include influxdb::profile::toml +``` + +#### Parameters + +The following parameters are available in the `influxdb::profile::toml` class: + +* [`version`](#version) + +##### `version` + +Data type: `String` + + + +Default value: `'2.1.1'` + +## Resource types + +### `influxdb_auth` + +Manages authentication tokens in InfluxDB + +#### Examples + +##### + +```puppet +influxdb_auth {"telegraf read token": + ensure => present, + org => 'my_org' + permissions => [ + { + "action" => "read", + "resource" => { + "type" => "telegrafs" + } + }, + ], +} +``` + +#### Properties + +The following properties are available in the `influxdb_auth` type. + +##### `ensure` + +Data type: `Enum[present, absent]` + +Whether the token should be present or absent on the target system. + +Default value: `present` + +##### `host` + +Data type: `Optional[String]` + +The host running InfluxDB + +##### `name` + +Data type: `String` + +Name of the token. Note that InfluxDB does not currently have a human readable identifer for token, so for convinience we use the description property as the namevar of this resource + +##### `org` + +Data type: `String` + +The organization that owns the token + +##### `permissions` + +Data type: `Array[Hash]` + +List of permissions granted by the token + +##### `port` + +Data type: `Optional[Integer]` + +Port used by the InfluxDB service + +Default value: `8086` + +##### `status` + +Data type: `Enum[active, inactive]` + +Status of the token + +Default value: `active` + +##### `token` + +Data type: `Optional[Sensitive[String]]` + +Administrative token used for authenticating API calls + +##### `token_file` + +Data type: `Optional[String]` + +File on disk containing an administrative token + +##### `use_ssl` + +Data type: `Boolean` + +Whether to enable SSL for the InfluxDB service + +Default value: `true` + +##### `user` + +Data type: `Optional[String]` + +User to scope authorization to + +### `influxdb_bucket` + +Manages InfluxDB buckets + +#### Examples + +##### + +```puppet +influxdb_bucket {'my_bucket': + ensure => present, + org => 'my_org', + labels => ['my_label1', 'my_label2'], + require => Influxdb_org['my_org'], +} +``` + +#### Properties + +The following properties are available in the `influxdb_bucket` type. + +##### `create_dbrp` + +Data type: `Boolean` + +Whether to create a "database retention policy" mapping to allow for legacy access + +Default value: `true` + +##### `ensure` + +Data type: `Enum[present, absent]` + +Whether the bucket should be present or absent on the target system. + +Default value: `present` + +##### `host` + +Data type: `Optional[String]` + +The host running InfluxDB + +##### `labels` + +Data type: `Optional[Array[String]]` + +Labels to apply to the bucket. For convenience, these will be created automatically without the need to create influxdb_label resources + +##### `members` + +Data type: `Optional[Array[String]]` + +List of users to add as members of the bucket. For convenience, these will be created automatically without the need to create influxdb_user resources + +##### `name` + +Data type: `String` + +Name of the bucket + +##### `org` + +Data type: `String` + +Organization which the buckets belongs to + +##### `port` + +Data type: `Optional[Integer]` + +Port used by the InfluxDB service + +Default value: `8086` + +##### `retention_rules` + +Data type: `Array` + +Rules to determine retention of data inside the bucket + +Default value: `[{"type"=>"expire", "everySeconds"=>0, "shardGroupDurationSeconds"=>604800}]` + +##### `token` + +Data type: `Optional[Sensitive[String]]` + +Administrative token used for authenticating API calls + +##### `token_file` + +Data type: `Optional[String]` + +File on disk containing an administrative token + +##### `use_ssl` + +Data type: `Boolean` + +Whether to enable SSL for the InfluxDB service + +Default value: `true` + +### `influxdb_dbrp` + +This type provides the ability to manage InfluxDB dbrps + +#### Examples + +##### + +```puppet +influxdb_dbrp {'my_bucket': + ensure => present, + org => 'my_org', + bucket => 'my_bucket', + rp => 'Forever', +} +``` + +#### Properties + +The following properties are available in the `influxdb_dbrp` type. + +##### `bucket` + +Data type: `String` + +The bucket to map to the retention policy to + +##### `ensure` + +Data type: `Enum[present, absent]` + +Whether the dbrp should be present or absent on the target system. + +Default value: `present` + +##### `host` + +Data type: `Optional[String]` + +The host running InfluxDB + +##### `is_default` + +Data type: `Optional[Boolean]` + +Whether this should be the default policy + +Default value: `true` + +##### `name` + +Data type: `String` + +Name of the dbrp to manage in InfluxDB + +##### `org` + +Data type: `String` + +Name of the organization that owns the mapping + +##### `port` + +Data type: `Optional[Integer]` + +Port used by the InfluxDB service + +Default value: `8086` + +##### `rp` + +Data type: `String` + +Name of the InfluxDB 1.x retention policy + +##### `token` + +Data type: `Optional[Sensitive[String]]` + +Administrative token used for authenticating API calls + +##### `token_file` + +Data type: `Optional[String]` + +File on disk containing an administrative token + +##### `use_ssl` + +Data type: `Boolean` + +Whether to enable SSL for the InfluxDB service + +Default value: `true` + +### `influxdb_label` + +Manages labels in InfluxDB + +#### Examples + +##### + +```puppet +influxdb_label {'puppetlabs/influxdb': + ensure => present, + org => 'puppetlabs', +} +``` + +#### Properties + +The following properties are available in the `influxdb_label` type. + +##### `ensure` + +Data type: `Enum[present, absent]` + +Whether the label should be present or absent on the target system. + +Default value: `present` + +##### `host` + +Data type: `Optional[String]` + +The host running InfluxDB + +##### `name` + +Data type: `String` + +Name of the label + +##### `org` + +Data type: `String` + +Organization the label belongs to + +##### `port` + +Data type: `Optional[Integer]` + +Port used by the InfluxDB service + +Default value: `8086` + +##### `properties` + +Data type: `Optional[Hash]` + +Key/value pairs associated with the label + +##### `token` + +Data type: `Optional[Sensitive[String]]` + +Administrative token used for authenticating API calls + +##### `token_file` + +Data type: `Optional[String]` + +File on disk containing an administrative token + +##### `use_ssl` + +Data type: `Boolean` + +Whether to enable SSL for the InfluxDB service + +Default value: `true` + +### `influxdb_org` + +Manages organizations in InfluxDB + +#### Examples + +##### + +```puppet +influxdb_org {'puppetlabs': + ensure => present, +} +``` + +#### Properties + +The following properties are available in the `influxdb_org` type. + +##### `description` + +Data type: `Optional[String]` + +Optional description for a given org + +##### `ensure` + +Data type: `Enum[present, absent]` + +Whether the organization should be present or absent on the target system. + +Default value: `present` + +##### `host` + +Data type: `Optional[String]` + +The host running InfluxDB + +##### `members` + +Data type: `Optional[Array[String]]` + +A list of users to add as members of the organization + +##### `name` + +Data type: `String` + +Name of the organization to manage in InfluxDB + +##### `port` + +Data type: `Optional[Integer]` + +Port used by the InfluxDB service + +Default value: `8086` + +##### `token` + +Data type: `Optional[Sensitive[String]]` + +Administrative token used for authenticating API calls + +##### `token_file` + +Data type: `Optional[String]` + +File on disk containing an administrative token + +##### `use_ssl` + +Data type: `Boolean` + +Whether to enable SSL for the InfluxDB service + +Default value: `true` + +### `influxdb_setup` + +Manages initial setup of InfluxDB. It is recommended to use the influxdb::install class instead of this resource directly. + +#### Examples + +##### + +```puppet +influxdb_setup {'': + ensure => 'present', + token_file => , + bucket => 'my_bucket', + org => 'my_org', + username => 'admin', + password => 'admin', +} +``` + +#### Properties + +The following properties are available in the `influxdb_setup` type. + +##### `bucket` + +Data type: `String` + +Name of the initial bucket to create + +##### `ensure` + +Data type: `Enum[present, absent]` + +Whether initial setup has been performed. present/absent is determined by the response from the /setup api + +Default value: `present` + +##### `host` + +Data type: `Optional[String]` + +The host running InfluxDB + +##### `org` + +Data type: `String` + +Name of the initial organization to create + +##### `password` + +Data type: `Sensitive[String]` + +Initial admin user password + +##### `port` + +Data type: `Optional[Integer]` + +Port used by the InfluxDB service + +Default value: `8086` + +##### `token` + +Data type: `Optional[Sensitive[String]]` + +Administrative token used for authenticating API calls + +##### `token_file` + +Data type: `Optional[String]` + +File on disk containing an administrative token + +##### `use_ssl` + +Data type: `Boolean` + +Whether to enable SSL for the InfluxDB service + +Default value: `true` + +##### `username` + +Data type: `String` + +Name of the initial admin user + +#### Parameters + +The following parameters are available in the `influxdb_setup` type. + +* [`name`](#name) + +##### `name` + +namevar + +Data type: `String` + +The fqdn of the host running InfluxDB + +### `influxdb_user` + +Manages users in InfluxDB. Note that currently, passwords can only be set upon creating the user and must be updated manually using the cli. A user must be added to an organization to be able to log in. + +#### Examples + +##### + +```puppet +influxdb_user {'bob': + ensure => present, + password => Sensitive('thisisbobspassword'), +} + +influxdb_org {'my_org': + ensure => present, + members => ['bob'], +} +``` + +#### Properties + +The following properties are available in the `influxdb_user` type. + +##### `ensure` + +Data type: `Enum[present, absent]` + +Whether the user should be present or absent on the target system. + +Default value: `present` + +##### `host` + +Data type: `Optional[String]` + +The host running InfluxDB + +##### `name` + +Data type: `String` + +Name of the user + +##### `password` + +Data type: `Optional[Sensitive[String]]` + +User password + +##### `port` + +Data type: `Optional[Integer]` + +Port used by the InfluxDB service + +Default value: `8086` + +##### `status` + +Data type: `Enum[active, inactive]` + +Status of the user + +Default value: `active` + +##### `token` + +Data type: `Optional[Sensitive[String]]` + +Administrative token used for authenticating API calls + +##### `token_file` + +Data type: `Optional[String]` + +File on disk containing an administrative token + +##### `use_ssl` + +Data type: `Boolean` + +Whether to enable SSL for the InfluxDB service + +Default value: `true` + +## Functions + +### `influxdb::from_toml` + +Type: Ruby 4.x API + +The influxdb::from_toml function. + +#### `influxdb::from_toml(String $file)` + +The influxdb::from_toml function. + +Returns: `Any` + +##### `file` + +Data type: `String` + + + +### `influxdb::hosts_with_pe_profile` + +Type: Puppet Language + +The influxdb::hosts_with_pe_profile function. + +#### `influxdb::hosts_with_pe_profile(String $profile)` + +The influxdb::hosts_with_pe_profile function. + +Returns: `Array` + +##### `profile` + +Data type: `String` + + + +### `influxdb::retrieve_token` + +Type: Ruby 4.x API + +The influxdb::retrieve_token function. + +#### `influxdb::retrieve_token(String $uri, Sensitive[String] $admin_token, String $token_name)` + +The influxdb::retrieve_token function. + +Returns: `Any` + +##### `uri` + +Data type: `String` + + + +##### `admin_token` + +Data type: `Sensitive[String]` + + + +##### `token_name` + +Data type: `String` + + + +### `influxdb::to_toml` + +Type: Ruby 4.x API + +The influxdb::to_toml function. + +#### `influxdb::to_toml(Hash $hash)` + +The influxdb::to_toml function. + +Returns: `Any` + +##### `hash` + +Data type: `Hash` + + + diff --git a/metadata.json b/metadata.json index d27fffa..276f4a8 100644 --- a/metadata.json +++ b/metadata.json @@ -1,12 +1,15 @@ { "name": "puppetlabs-influxdb", - "version": "0.1.0", + "version": "0.2.0", "author": "Adrian Parreiras Horta", "summary": "Installs and configures InfluxDB 2", "license": "Apache-2.0", "source": "https://github.com/puppetlabs/influxdb", "dependencies": [ - { "name":"puppet/archive","version_requirement":">= 6.0.0 <7.0" } + { + "name": "puppet/archive", + "version_requirement": ">= 6.0.0 <7.0" + } ], "operatingsystem_support": [ {