make readme readme
Signed-off-by: Nico Schottelius <nico@kr.ethz.ch>
This commit is contained in:
Nico Schottelius
parent
070a1d6e0c
commit
3bbf032b41
2 changed files with 219 additions and 220 deletions
1
README
1
README
|
|
@ -1 +0,0 @@
|
||||||
cdist.mdwn
|
|
||||||
219
README
Normal file
219
README
Normal file
|
|
@ -0,0 +1,219 @@
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
cdist configures your system. It is similar to
|
||||||
|
[cfengine](http://www.cfengine.org/) and [puppet](http://www.puppetlabs.com/).
|
||||||
|
It is inspired by both of those tools:
|
||||||
|
|
||||||
|
* Try to redo the great power you get
|
||||||
|
* But leave out the bugs you also got
|
||||||
|
|
||||||
|
And cdist is UNIX:
|
||||||
|
|
||||||
|
It's designed to reuse existing tools,
|
||||||
|
does not require high level scripting language interpreters
|
||||||
|
and is equipped with manpages.
|
||||||
|
|
||||||
|
### Architecture
|
||||||
|
|
||||||
|
* KISS (keep it simple and stupid)
|
||||||
|
* Allow very easy extension of cdist (creating own types for instance)
|
||||||
|
* Push (server pushes configuration) and Pull (client retrieves config) supported
|
||||||
|
* User defines configuration in shell scripts using cdist functions
|
||||||
|
* Cdist generates internal configuration (cconfig style) and afterwards applies configuration
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
### Server
|
||||||
|
|
||||||
|
* A posix like shell
|
||||||
|
* SSH-Client (for push architecture)
|
||||||
|
* SSH-Server (for pull architecture)
|
||||||
|
|
||||||
|
### Client
|
||||||
|
|
||||||
|
* A posix like shell
|
||||||
|
* SSH-Client (for pull architecture)
|
||||||
|
* SSH-Server (for push architecture)
|
||||||
|
|
||||||
|
## How to get cdist
|
||||||
|
|
||||||
|
git clone git://git.schottelius.org/cdist
|
||||||
|
|
||||||
|
## How to install cdist
|
||||||
|
|
||||||
|
make install
|
||||||
|
|
||||||
|
## How to use cdist
|
||||||
|
|
||||||
|
man cdist
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
## How cdist works
|
||||||
|
|
||||||
|
### Exploring your system
|
||||||
|
|
||||||
|
cdist analyses the system to apply the configuration on and
|
||||||
|
selects the right backends. You can use ***cdist-explore*** to
|
||||||
|
the results of the explore functions.
|
||||||
|
|
||||||
|
### Applying the configuration
|
||||||
|
|
||||||
|
cdist looks for the configuration to apply on the local host
|
||||||
|
and applies it using ***cdist-apply***.
|
||||||
|
|
||||||
|
### Managing many hosts
|
||||||
|
|
||||||
|
Whereas ***cdist-apply*** manages one host, ***cdist-deploy***
|
||||||
|
applies the configuration on enabled hosts.
|
||||||
|
|
||||||
|
## How to use cdist?
|
||||||
|
|
||||||
|
0. Create a host specification (/etc/cdist/hosts/**hostname**)
|
||||||
|
0. Add functionalilty to add
|
||||||
|
0. Run ***cdist-apply***
|
||||||
|
|
||||||
|
|
||||||
|
## What do I need [from puppet?]
|
||||||
|
|
||||||
|
### Abstraction of package managers
|
||||||
|
|
||||||
|
I don't want to care about apt, rpm, yum, pacman, etc. I just
|
||||||
|
want to ensure, some package exists or does not exist.
|
||||||
|
|
||||||
|
|
||||||
|
### Common tasks already done
|
||||||
|
|
||||||
|
- [LIBRARY] All the helper types like
|
||||||
|
- file
|
||||||
|
- ssh_keys
|
||||||
|
- package
|
||||||
|
- service
|
||||||
|
- user
|
||||||
|
|
||||||
|
### PORTABILITY
|
||||||
|
- [PORTABILITY] clients for every unix
|
||||||
|
- mostly ruby + facter in puppet
|
||||||
|
|
||||||
|
### Other
|
||||||
|
- Modules: Nice to put stuff together
|
||||||
|
- and reuse
|
||||||
|
- [CONDITIONS] facter is cool
|
||||||
|
- the DSL
|
||||||
|
- with many bugs
|
||||||
|
- templates
|
||||||
|
- Client/Server approach is nice to have
|
||||||
|
- Clients only get the part of the documentation, that's
|
||||||
|
relevant to them
|
||||||
|
- detect impossible/unsafe things:
|
||||||
|
- creating a file twice
|
||||||
|
- installing and removing a package
|
||||||
|
- and report location of occurence
|
||||||
|
- parse afterwards?
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
what is puppet? [FOR ME]
|
||||||
|
|
||||||
|
A configuration deployment assistant,
|
||||||
|
a DSL that allows you define the objectives.
|
||||||
|
A webserver with fileserver capabilities.
|
||||||
|
A client based scheduled polling infrastructure.
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
What do I miss from puppet?
|
||||||
|
|
||||||
|
- speed
|
||||||
|
- elegance
|
||||||
|
- clean design
|
||||||
|
- documentation
|
||||||
|
- the "no surprise" factor
|
||||||
|
- easy to use "data memory" (i.e. external ressources)
|
||||||
|
- easy integration into installation process
|
||||||
|
- copy identity to master
|
||||||
|
- multi master setups
|
||||||
|
- development configurations / tests
|
||||||
|
- editing of configuration files
|
||||||
|
- similar to cfengine
|
||||||
|
- replace bug squasher with bug avoidance
|
||||||
|
- qmail did not need one either
|
||||||
|
- push infrastructure
|
||||||
|
- real / meaningful error messages
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
Simple stuff done by Unix[notm]
|
||||||
|
|
||||||
|
- DSL: Shell!
|
||||||
|
- gives if, else and EVEN elsif for free!
|
||||||
|
- and case
|
||||||
|
- and and and
|
||||||
|
- and there's no os (solaris doesn't count) without a usable /bin/sh
|
||||||
|
- cdist defines what you can use
|
||||||
|
- you _can_ use os specific stuff
|
||||||
|
- but it's ugly and you shoot into your own foot
|
||||||
|
- "manifests" (use the same name here?) will be run/sourced
|
||||||
|
- inheritance possible via sourcing
|
||||||
|
- cdist-lib always preloaded
|
||||||
|
- library == functions?
|
||||||
|
- version control via git
|
||||||
|
- file distribution via ssh
|
||||||
|
- authentication via ssh
|
||||||
|
- dumb clients, similar to manifest compile in puppet
|
||||||
|
- clients just execute commands
|
||||||
|
- dependencies via make?
|
||||||
|
- how to ensure sigletons / conflicting definitions?
|
||||||
|
file { "/a":
|
||||||
|
ensure => present,
|
||||||
|
file { "/a":
|
||||||
|
ensure => absent,
|
||||||
|
- matching on explored items, not only on host name?
|
||||||
|
- match function in host? [optional]
|
||||||
|
- file source:
|
||||||
|
- relative to specification
|
||||||
|
- or absolute
|
||||||
|
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
Implementation
|
||||||
|
|
||||||
|
"cdist-server"
|
||||||
|
-> called by cron?
|
||||||
|
-> no need to reimplement scheduling
|
||||||
|
"cdist-explore" (facter replacement)
|
||||||
|
-> running on the client
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
Requirements:
|
||||||
|
It MUST be incredible easy/dumb to add new types.
|
||||||
|
=> growable default types
|
||||||
|
|
||||||
|
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
## TO DOC
|
||||||
|
|
||||||
|
Before initial release, document:
|
||||||
|
|
||||||
|
- how to add package backends
|
||||||
|
- how to write a minimal host manifest
|
||||||
|
- create library with all functions (and their parameters)
|
||||||
|
- cdist_package
|
||||||
|
- cdist_file
|
||||||
|
- cdist_dir
|
||||||
|
|
||||||
|
- only do necessary work
|
||||||
|
- install packages only if not existent
|
||||||
|
- copy file only if different
|
||||||
|
|
||||||
|
- how to write a module
|
||||||
|
- module function autoloading via *.sh
|
||||||
|
- module "manifest"?
|
||||||
|
- create functions in *.sh
|
||||||
|
- name functions "modulename_function"
|
||||||
|
module hellow
|
||||||
|
function kitty
|
||||||
|
=> hellow_kitty
|
||||||
|
- you are advised (not forced) to put files
|
||||||
|
to a subdirectory named "files"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
219
cdist.mdwn
219
cdist.mdwn
|
|
@ -1,219 +0,0 @@
|
||||||
## Introduction
|
|
||||||
|
|
||||||
cdist configures your system. It is similar to
|
|
||||||
[cfengine](http://www.cfengine.org/) and [puppet](http://www.puppetlabs.com/).
|
|
||||||
It is inspired by both of those tools:
|
|
||||||
|
|
||||||
* Try to redo the great power you get
|
|
||||||
* But leave out the bugs you also got
|
|
||||||
|
|
||||||
And cdist is UNIX:
|
|
||||||
|
|
||||||
It's designed to reuse existing tools,
|
|
||||||
does not require high level scripting language interpreters
|
|
||||||
and is equipped with manpages.
|
|
||||||
|
|
||||||
### Architecture
|
|
||||||
|
|
||||||
* KISS (keep it simple and stupid)
|
|
||||||
* Allow very easy extension of cdist (creating own types for instance)
|
|
||||||
* Push (server pushes configuration) and Pull (client retrieves config) supported
|
|
||||||
* User defines configuration in shell scripts using cdist functions
|
|
||||||
* Cdist generates internal configuration (cconfig style) and afterwards applies configuration
|
|
||||||
|
|
||||||
## Requirements
|
|
||||||
|
|
||||||
### Server
|
|
||||||
|
|
||||||
* A posix like shell
|
|
||||||
* SSH-Client (for push architecture)
|
|
||||||
* SSH-Server (for pull architecture)
|
|
||||||
|
|
||||||
### Client
|
|
||||||
|
|
||||||
* A posix like shell
|
|
||||||
* SSH-Client (for pull architecture)
|
|
||||||
* SSH-Server (for push architecture)
|
|
||||||
|
|
||||||
## How to get cdist
|
|
||||||
|
|
||||||
git clone git://git.schottelius.org/cdist
|
|
||||||
|
|
||||||
## How to install cdist
|
|
||||||
|
|
||||||
make install
|
|
||||||
|
|
||||||
## How to use cdist
|
|
||||||
|
|
||||||
man cdist
|
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
|
|
||||||
## How cdist works
|
|
||||||
|
|
||||||
### Exploring your system
|
|
||||||
|
|
||||||
cdist analyses the system to apply the configuration on and
|
|
||||||
selects the right backends. You can use ***cdist-explore*** to
|
|
||||||
the results of the explore functions.
|
|
||||||
|
|
||||||
### Applying the configuration
|
|
||||||
|
|
||||||
cdist looks for the configuration to apply on the local host
|
|
||||||
and applies it using ***cdist-apply***.
|
|
||||||
|
|
||||||
### Managing many hosts
|
|
||||||
|
|
||||||
Whereas ***cdist-apply*** manages one host, ***cdist-deploy***
|
|
||||||
applies the configuration on enabled hosts.
|
|
||||||
|
|
||||||
## How to use cdist?
|
|
||||||
|
|
||||||
0. Create a host specification (/etc/cdist/hosts/**hostname**)
|
|
||||||
0. Add functionalilty to add
|
|
||||||
0. Run ***cdist-apply***
|
|
||||||
|
|
||||||
|
|
||||||
## What do I need [from puppet?]
|
|
||||||
|
|
||||||
### Abstraction of package managers
|
|
||||||
|
|
||||||
I don't want to care about apt, rpm, yum, pacman, etc. I just
|
|
||||||
want to ensure, some package exists or does not exist.
|
|
||||||
|
|
||||||
|
|
||||||
### Common tasks already done
|
|
||||||
|
|
||||||
- [LIBRARY] All the helper types like
|
|
||||||
- file
|
|
||||||
- ssh_keys
|
|
||||||
- package
|
|
||||||
- service
|
|
||||||
- user
|
|
||||||
|
|
||||||
### PORTABILITY
|
|
||||||
- [PORTABILITY] clients for every unix
|
|
||||||
- mostly ruby + facter in puppet
|
|
||||||
|
|
||||||
### Other
|
|
||||||
- Modules: Nice to put stuff together
|
|
||||||
- and reuse
|
|
||||||
- [CONDITIONS] facter is cool
|
|
||||||
- the DSL
|
|
||||||
- with many bugs
|
|
||||||
- templates
|
|
||||||
- Client/Server approach is nice to have
|
|
||||||
- Clients only get the part of the documentation, that's
|
|
||||||
relevant to them
|
|
||||||
- detect impossible/unsafe things:
|
|
||||||
- creating a file twice
|
|
||||||
- installing and removing a package
|
|
||||||
- and report location of occurence
|
|
||||||
- parse afterwards?
|
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
what is puppet? [FOR ME]
|
|
||||||
|
|
||||||
A configuration deployment assistant,
|
|
||||||
a DSL that allows you define the objectives.
|
|
||||||
A webserver with fileserver capabilities.
|
|
||||||
A client based scheduled polling infrastructure.
|
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
What do I miss from puppet?
|
|
||||||
|
|
||||||
- speed
|
|
||||||
- elegance
|
|
||||||
- clean design
|
|
||||||
- documentation
|
|
||||||
- the "no surprise" factor
|
|
||||||
- easy to use "data memory" (i.e. external ressources)
|
|
||||||
- easy integration into installation process
|
|
||||||
- copy identity to master
|
|
||||||
- multi master setups
|
|
||||||
- development configurations / tests
|
|
||||||
- editing of configuration files
|
|
||||||
- similar to cfengine
|
|
||||||
- replace bug squasher with bug avoidance
|
|
||||||
- qmail did not need one either
|
|
||||||
- push infrastructure
|
|
||||||
- real / meaningful error messages
|
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
Simple stuff done by Unix[notm]
|
|
||||||
|
|
||||||
- DSL: Shell!
|
|
||||||
- gives if, else and EVEN elsif for free!
|
|
||||||
- and case
|
|
||||||
- and and and
|
|
||||||
- and there's no os (solaris doesn't count) without a usable /bin/sh
|
|
||||||
- cdist defines what you can use
|
|
||||||
- you _can_ use os specific stuff
|
|
||||||
- but it's ugly and you shoot into your own foot
|
|
||||||
- "manifests" (use the same name here?) will be run/sourced
|
|
||||||
- inheritance possible via sourcing
|
|
||||||
- cdist-lib always preloaded
|
|
||||||
- library == functions?
|
|
||||||
- version control via git
|
|
||||||
- file distribution via ssh
|
|
||||||
- authentication via ssh
|
|
||||||
- dumb clients, similar to manifest compile in puppet
|
|
||||||
- clients just execute commands
|
|
||||||
- dependencies via make?
|
|
||||||
- how to ensure sigletons / conflicting definitions?
|
|
||||||
file { "/a":
|
|
||||||
ensure => present,
|
|
||||||
file { "/a":
|
|
||||||
ensure => absent,
|
|
||||||
- matching on explored items, not only on host name?
|
|
||||||
- match function in host? [optional]
|
|
||||||
- file source:
|
|
||||||
- relative to specification
|
|
||||||
- or absolute
|
|
||||||
|
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
Implementation
|
|
||||||
|
|
||||||
"cdist-server"
|
|
||||||
-> called by cron?
|
|
||||||
-> no need to reimplement scheduling
|
|
||||||
"cdist-explore" (facter replacement)
|
|
||||||
-> running on the client
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
Requirements:
|
|
||||||
It MUST be incredible easy/dumb to add new types.
|
|
||||||
=> growable default types
|
|
||||||
|
|
||||||
|
|
||||||
--------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
## TO DOC
|
|
||||||
|
|
||||||
Before initial release, document:
|
|
||||||
|
|
||||||
- how to add package backends
|
|
||||||
- how to write a minimal host manifest
|
|
||||||
- create library with all functions (and their parameters)
|
|
||||||
- cdist_package
|
|
||||||
- cdist_file
|
|
||||||
- cdist_dir
|
|
||||||
|
|
||||||
- only do necessary work
|
|
||||||
- install packages only if not existent
|
|
||||||
- copy file only if different
|
|
||||||
|
|
||||||
- how to write a module
|
|
||||||
- module function autoloading via *.sh
|
|
||||||
- module "manifest"?
|
|
||||||
- create functions in *.sh
|
|
||||||
- name functions "modulename_function"
|
|
||||||
module hellow
|
|
||||||
function kitty
|
|
||||||
=> hellow_kitty
|
|
||||||
- you are advised (not forced) to put files
|
|
||||||
to a subdirectory named "files"
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Loading…
Reference in a new issue