4.4 KiB
OS Secret-store Plugin
The os plugin allows to manage and store secrets using the native Operating
System keyring. For Windows this plugin uses the credential manager, on Linux
the kernel keyring is used and on MacOS we use the Keychain implementation.
To manage your secrets you can either use the secrets command of Telegraf or the tools that natively comes with your operating system.
Configuration
The configuration differs slightly depending on the Operating System. We first describe the common options here and the refer to the individual interpretation or options in the following sections.
All secret-store implementations require an id to be able to reference the
store when specifying the secret. The id needs to be unique in the
configuration.
For all operating systems, the keyring name can be chosen using the keyring
parameter. However, the interpretation is slightly different on the individual
implementations.
The dynamic flag allows to indicate secrets that change during the runtime of
Telegraf. I.e. when set to true, the secret will be read from the secret-store
on every access by a plugin. If set to false, all secrets in the secret store
are assumed to be static and are only read once at startup of Telegraf.
Docker
Access to the kernel keyring is disabled by default in docker containers
(see documentation).
In this case you will get an
opening keyring failed: Specified keyring backend not available error!
You can enable access to the kernel keyring, but as the keyring is not namespaced, you should be aware of the security implication! One implication is for example that keys added in one container are accessible by all other containers running on the same host, not only within the same container.
Windows
# Operating System native secret-store
[[secretstores.os]]
## Unique identifier for the secret-store.
## This id can later be used in plugins to reference the secrets
## in this secret-store via @{<id>:<secret_key>} (mandatory)
id = "secretstore"
## Keyring of the secrets
## In Windows, keys follow a fixed pattern in the form `<keyring>:<collection>:<key>`. Please keep this in mind
## when creating secrets with the Windows credential tool.
# keyring = "telegraf"
# collection = ""
## Allow dynamic secrets that are updated during runtime of telegraf
# dynamic = false
On Windows you can use the Credential Manager Control panel or
Telegraf to manage your secrets.
Please use generic credentials and respect the special
<keyring>:<collection>:<key> format of the secret key. The
secret value needs to be stored in the Password field.
Linux
# Operating System native secret-store
[[secretstores.os]]
## Unique identifier for the secret-store.
## This id can later be used in plugins to reference the secrets
## in this secret-store via @{<id>:<secret_key>} (mandatory)
id = "secretstore"
## Keyring name used for the secrets
# keyring = "telegraf"
## Allow dynamic secrets that are updated during runtime of telegraf
# dynamic = false
On Linux the kernel keyring in the user scope is used to store the
secrets. The collection setting is ignored on Linux.
MacOS
# Operating System native secret-store
[[secretstores.os]]
## Unique identifier for the secret-store.
## This id can later be used in plugins to reference the secrets
## in this secret-store via @{<id>:<secret_key>} (mandatory)
id = "secretstore"
## MacOS' Keychain name and service name
# keyring = "telegraf"
# collection = ""
## MacOS' Keychain password
## If no password is specified here, Telegraf will prompt for it at startup time.
# password = ""
## Allow dynamic secrets that are updated during runtime of telegraf
# dynamic = false
On MacOS the Keychain implementation is used. Here the keyring parameter
corresponds to the Keychain name and the collection to the optional Keychain
service name. Additionally a password is required to access the Keychain.
The password itself is also a secret and can be a string, an environment
variable or a reference to a secret stored in another secret-store.
If password is omitted, you will be prompted for the password on startup.