cdist/doc/internal/type-integration

This document is a brainstorming document, on how to integrate types.

Proposed/discussed structures:

1) 2010-11-02
   $basedir/$type/
      properties/
         name/
            required # required | optional
         choices  # \n liste
            

      meta/
         default (shell script)
      types/
         pukman/

2) 2010-11-09

How to write my own type named "coffee":

   Create the directory /etc/cdist/types/coffee/
   Create the file /etc/cdist/types/coffee/README containing a description of the 
type.
   If your type supports attributes, create the directory /etc/cdist/types/coffee/
attributes.
   For each attribute, create the file
      /etc/cdist/types/coffee/attributes/$attribute_name which contains

      a short description on the first line
      then a blank line
      then a long description (probably over several lines)

   If you think your type may be useful for others, submit it for inclusion
   into cdist at cdist -- at -- l.schottelius.org.

   Create /etc/cdist/types/coffee/init which reads $configinput
   (either via cconfig or via environment) and outputs a block of
   shell code suitable for running on the client.



--------------------------------------------------------------------------------
type layout:

   <name>/
      config   # binary that is called to adjust cconfig tree
      change   # binary that is called on the remote host?
--------------------------------------------------------------------------------
cdist view on types:

How types are integrated/run:

   First stage:
   - If cdist encounters type in manifest,
     a wrapper script is run, that creates a
     new entry in the cconfig database and adds
     attribute values. This defines a cconfig
     tree, that may look as follows:
      
      <hostname>/<type>/<id>/<parameters>:

      myhost/__file/cdist_bin/source
      myhost/__file/cdist_bin/destination
      ...

   - In this stage, no conflicts may occur, as
     no type code has been called (i.e. only
     manifests, which map config to hosts is
     applied).

   Second stage:
   - The "manifest" script of every used type
     (i.e. the manifests created at least one object)
     is called, which again is able to call other
     types. All created objects may also be modified
     by the type.

     For instance a "httpd" type may call the
     "webroot" type with --path / ... 
     # FIND CASE WHERE SENSEFUL => look through
     current puppet config

   - The newly created objects are merged back into
     the existing tree. No conflicts may occur during
     the merge, because this would implicit that the
     type conflicts with other types.

     The idea of this that a type may expand another
     type with functionality, but may need to adjust
     ("overwrite") settings from the original type.

   Third stage:
   - Cdist calls the "gencode" binary of the types
     for every created object. This binary should create
     code to be executed on the target on stdout.

     If the gencode binary fails, it must print diagnostic
     messages on stderr and exit non-zero.

     A description of what the generated code may/must/should
     do can be found at the end of this document.

   - Cdist merges together the generated code
     (taking care of DEPENDENCIES (which are not
     yet defined (take care, double nested brackets)))

   Fourth stage:
   - The resulting shell script is transferred
     to the target and executed.

--------------------------------------------------------------------------------
Scope of code execution on the client

   It should be assumed that the clients are pretty dumb
   and thus do not have high level tools like python
   installed.

   If a type requires specific tools to be present
   on the target, there must be another type that
   provides this tool and the first type must create
   an object of the specific type.

   If the generated code fails on the client, it must
   print diagnostistic messages on stderr and call
   "exit 1", so the configuration is aborted.