github.com/flanksource/konfigadm@v0.12.0/DESIGN.md (about)

     1  
     2  ![](./docs/konfigadm.png)
     3  
     4  # Design Principles
     5  
     6  `konfigadm` differs from tools like ansible, puppet and chef in that it uses a Virtual Filesystem and Shell (VFS), configuration items don't actually make changes, they only update the VFS, changes to the system are only made from the VFS in the final step.
     7  
     8  The declarative model (VFS) has a number of advantages over imperative tools where changes are parsed and applied in the same step:
     9  
    10  * Unit testing across multiple different configurations becomes trivial
    11  * The VFS can be "compliled" into cloud-init, or inspected to verify state after application
    12  * "Operators" can easily be built that emit other configuration items, these are easily unit and integration testable
    13  
    14  `konfigadm` differs to CFEngine in that it does not have any control flows (explicit or implicit) and the "model" only includes 2 low-level items, shell commands and files.
    15  
    16  ## Goals
    17  
    18  * Avoid entire classes of common problems in configuration management by reducing the feature-set
    19  * Simple mental model, that is easy to learn and test against by leveraging declarative configuration following the kubernetes model
    20  * Batteries included for kubernetes environments
    21  * Usable within tools as a go module or standalone as a CLI
    22  * Support the notion of different environments (OS, Cloud) natively without the need for control flow
    23  
    24  ## Non-Goals
    25  
    26  * Be a generic replacement for ansible / cloud-init
    27  * Remote execution (The output of konfigadm can be fed into a remote execution engine)
    28  * Control flow (If/when, loops, etc)
    29  
    30  ### Common Problems with ansible/puppet/chef
    31  
    32  * Trying to install ansible, but requiring a specific version of python
    33  * Installing python, but then requiring a specific version of a pip module in order to execute a  specific task
    34  * Having a playbook work today, but break tomorrow because ansible or python modules have been upgraded / downgraded
    35  * Running an ansible task and it reports a failure or success incorrectly, but you can't work out why, or how to reproduce it outside of ansible
    36  * Trying to support different operating systems, but then having to maintain separate playbooks
    37  * Calling the wrong playbook, because the when expression is wrong / error prone
    38  * Adding a conditional flow to a task, but specifying an incorrect / invalid condition
    39  * Attempting to call sub tasks / roles, but then having different variables reported from the sub-task
    40  
    41  Many of these issues could be mitigated by unit testing, however ansible is fundamentally not unit-testable, modules almost exclusively update  global state (by installing packages, updating files or running commands) and there is no way of checking what a module has done or wants todo. The dry-run capability is not universally supported and is self-reported.
    42  
    43  Integration testing with tools like molecule is possible, but cannot verify that no other changes were made.
    44  
    45  
    46  ### Common Problems with cloud-init
    47  
    48  * Trying to template out a cloud-init YAML file but then getting indentation wrong
    49  * Getting YAML indentation right, but then specifying a field in the wrong section
    50  * Attempting to use a field, but not having the requisite packages installed for it to work
    51  * Trying to support multiple environments within a single or group of YAML files
    52  
    53