diff --git a/doc/internal.REMOVE_PRE_1.0/cdist-types.CLEANUP+INTEGRATE_MAN b/doc/internal.REMOVE_PRE_1.0/cdist-types.CLEANUP+INTEGRATE_MAN deleted file mode 100644 index c7f7682f..00000000 --- a/doc/internal.REMOVE_PRE_1.0/cdist-types.CLEANUP+INTEGRATE_MAN +++ /dev/null @@ -1,127 +0,0 @@ -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: - - / - 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: - - ///: - - 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. - diff --git a/doc/man/cdist-types.text b/doc/man/cdist-types.text index deea7971..828fa665 100644 --- a/doc/man/cdist-types.text +++ b/doc/man/cdist-types.text @@ -17,6 +17,133 @@ underscores, because types will be executed and thus you prevent collisions with real binaries (like "file"). +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: + + / + 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: [done] + - 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: + + ///: + + 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: [done] + - The "init" 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. + SEE ALSO --------