Nascent Plasticine Materialist

    dyconf

    1.1.0 • Public • Published

    dyconf

    dyconf can be used to generate a dynamically updated configuration from a template. It can also launch processes whenever a change is detected.

    dyconf is a tool, not a library. It is best suited to run inside a docker container.

    TL;DR you can find a working sample in consul-haproxy-dyconf.

    How does this compare to consul-template or confd?

    • dyconf is not tied to a specific backend. You can use it with ZooKeeper, etcd, ... or your own REST services.
    • It uses node.js so you have access to npm modules.
    • dyconf uses lodash templates which, if you know JavaScript, might be easier to grok than the golang text templates that are used by confd and consul-template.

    Install from npm

    npm install dyconf -g
    

    Usage

    usage: dyconf -config=FILE [OPTIONS]
    
      -config   path to the template configuration
      -dump     dumps the generated template to the console
      -q        quiet, no logs
    

    When you launch dyconf you need to specify -config=FILE, all other parameters are passed to the controller.

    Configuration

    The Hjson configuration defines the following settings:

    • controller: path to the JavaScript controller (see below)
    • outputFile: configuration file to write to
    • refreshInterval: refresh interval in seconds unless handled by the controller
    • syslog: set to true to run a syslog server and print to the console (useful with the docker logs command)
    • logFile: path to a logfile to tail and print to the console (similar to syslog above)
    • startup: a shell script to run at startup
    • reload: a shell script to run whenever the configuration changes
    • shutdown: a shell script to run at when the process is terminated
    • template: inline template that will produce the output file

    The controller can define additional settings.

    dyconf uses lodash.template.

    Controller

    The controller is a JavaScript module that is executed by dyconf.

    All controller functions are passed a context that contains:

    • args: CLI options (object)
    • argv: CLI arguments (array)
    • config: the template configuration
    • log: logging function
    • helpText: the standard help text (to append in init)

    The module needs to export:

    init

    function init(ctx, showHelp)

    init can be used to

    • evaluate commandline arguments,
    • create server connections (if any) or
    • show CLI help if showHelp is set.

    Return true to continue, false to exit.

    fetchData

    function fetchData(ctx)

    Use fetchData to collect data required for the template.

    Return a promise with the data that will be passed to the template.

    start (optional)

    function start(ctx, update)

    Starts the update process. If start is not supplied a fixed interval (refreshInterval) will be used.

    You can use start to watch for changes. Call update to trigger fetchData and to create/refresh the output file.

    Sample

    The Hello World source is available in the sample folder.

    config.hjson

    #hjson (go to http://hjson.org for details)
    {
      # define the controller that fetches the configuration and produces the content for outputFile
      controller: controller.js
      outputFile: /tmp/test.txt
    
      # refresh interval in seconds
      refreshInterval: 5
    
      # start a syslog server listening on port 514 (use rfc5424)
      # can be used to redirect logs for Docker
      syslog: false
    
      # logfile to tail to the console (can be "")
      # can be used like syslog for Docker
      logFile: ""
    
      # run on start/restart
      startup:
        '''
        # prepare, configure files or run any required processes
    
        # here you would launch the main process (e.g. haproxy)
        # for the sample we only show the outputFile
        cat /tmp/test.txt
        '''
    
      # reload a new configuration
      reload:
        '''
        # here you would tell the main process (e.g. haproxy)
        # to reload it's configuration
        # for the sample we only show the outputFile
        echo ---
        cat /tmp/test.txt
        '''
    
      # run on shutdown
      shutdown:
        '''
        # here you would kill the main process
        '''
    
      # define the template to generate the outputFile
      /*
      `random` was generated by the code in controller.js
      */
      template:
        '''
        <% [ "World", "Human" ].forEach(name => {
        %>Hello <%=name%>!
        <% }); %>
        In a real world scenario this file would contain the configuration generated by dyconf.
    
        Today's random value is <%=random%>!
        '''
    }
    

    controller.js

    // if you `require` any libraries you can add them to package.json &
    // run `npm i` in the directory that contains this file.
    
    var max;
    
    // init runs at startup to configure options and initialize prerequisites
    
    function init(ctx, showHelp) {
      var args=ctx.args;
    
      if (showHelp || ctx.argv.length>0) {
        console.error("usage: -max=#");
        console.error();
        console.error("  -max      max random sample value");
        console.error(ctx.helpText);
        return false;
      }
    
      max=parseInt(args.max||"999");
      return true;
    }
    
    // fetchData can be used to query an external service (like consul)
    // it needs to return a data structure that will be used to generate the template
    function fetchData(ctx) {
      return new Promise((resolve, reject) => resolve(Math.random()*max))
        .then(x => ({ random: x }));
    }
    
    // start the update process (optional)
    // can be used to implement a watch on a service
    function start(ctx, update) {
      setInterval(update, 1000);
      update();
    }
    
    module.exports={
      init: init,
      fetchData: fetchData,
      start: start,
    };
    

    Install

    npm i dyconf

    DownloadsWeekly Downloads

    1

    Version

    1.1.0

    License

    MIT

    Last publish

    Collaborators

    • laktak