github.com/influxdata/telegraf@v1.30.3/docs/SECRETSTORES.md (about)

     1  # Secret Store Plugins
     2  
     3  This section is for developers who want to create a new secret store plugin.
     4  
     5  ## Secret Store Plugin Guidelines
     6  
     7  * A secret store must conform to the [telegraf.SecretStore][] interface.
     8  * Secret-stores should call `secretstores.Add` in their `init` function to register
     9    themselves.  See below for a quick example.
    10  * To be available within Telegraf itself, plugins must register themselves
    11    using a file in `github.com/influxdata/telegraf/plugins/secretstores/all`
    12    named according to the plugin name. Make sure you also add build-tags to
    13    conditionally build the plugin.
    14  * Each plugin requires a file called `sample.conf` containing the sample
    15    configuration  for the plugin in TOML format. Please consult the
    16    [Sample Config][] page for the latest style guidelines.
    17  * Each plugin `README.md` file should include the `sample.conf` file in a
    18    section describing the configuration by specifying a `toml` section in the
    19    form `toml @sample.conf`. The specified file(s) are then injected
    20    automatically into the Readme.
    21  * Follow the recommended [Code Style][].
    22  
    23  [telegraf.SecretStore]: https://pkg.go.dev/github.com/influxdata/telegraf?utm_source=godoc#SecretStore
    24  [Sample Config]: https://github.com/influxdata/telegraf/blob/master/docs/developers/SAMPLE_CONFIG.md
    25  [Code Style]: https://github.com/influxdata/telegraf/blob/master/docs/developers/CODE_STYLE.md
    26  
    27  ## Secret Store Plugin Example
    28  
    29  ### Registration
    30  
    31  Registration of the plugin on `plugins/secretstores/all/printer.go`:
    32  
    33  ```go
    34  //go:build !custom || secretstores || secretstores.printer
    35  
    36  package all
    37  
    38  import _ "github.com/influxdata/telegraf/plugins/secretstores/printer" // register plugin
    39  ```
    40  
    41  The _build-tags_ in the first line allow to selectively include/exclude your
    42  plugin when customizing Telegraf.
    43  
    44  ### Plugin
    45  
    46  ```go
    47  //go:generate ../../../tools/readme_config_includer/generator
    48  package main
    49  
    50  import (
    51      _ "embed"
    52      "errors"
    53  
    54      "github.com/influxdata/telegraf"
    55      "github.com/influxdata/telegraf/plugins/secretstores"
    56  )
    57  
    58  //go:embed sample.conf
    59  var sampleConfig string
    60  
    61  type Printer struct {
    62      Log telegraf.Logger `toml:"-"`
    63  
    64      cache map[string]string
    65  }
    66  
    67  func (p *Printer) SampleConfig() string {
    68      return sampleConfig
    69  }
    70  
    71  func (p *Printer) Init() error {
    72      return nil
    73  }
    74  
    75  // Get searches for the given key and return the secret
    76  func (p *Printer) Get(key string) ([]byte, error) {
    77      v, found := p.cache[key]
    78      if !found {
    79          return nil, errors.New("not found")
    80      }
    81  
    82      return []byte(v), nil
    83  }
    84  
    85  // Set sets the given secret for the given key
    86  func (p *Printer) Set(key, value string) error {
    87      p.cache[key] = value
    88      return nil
    89  }
    90  
    91  // List lists all known secret keys
    92  func (p *Printer) List() ([]string, error) {
    93      keys := make([]string, 0, len(p.cache))
    94      for k := range p.cache {
    95          keys = append(keys, k)
    96      }
    97      return keys, nil
    98  }
    99  
   100  // GetResolver returns a function to resolve the given key.
   101  func (p *Printer) GetResolver(key string) (telegraf.ResolveFunc, error) {
   102      resolver := func() ([]byte, bool, error) {
   103          s, err := p.Get(key)
   104          return s, false, err
   105      }
   106      return resolver, nil
   107  }
   108  
   109  // Register the secret-store on load.
   110  func init() {
   111      secretstores.Add("printer", func(string) telegraf.SecretStore {
   112          return &Printer{}
   113      })
   114  }
   115  ```