doc: Massive update

1 files changed, 77 insertions, 0 deletions

diff --git a/doc/architecture/design.txt b/doc/architecture/design.txt
new file mode 100644
index 000000000..7008c601f
--- /dev/null
+++ b/doc/architecture/design.txt
@@ -0,0 +1,77 @@
+.. -*- mode: rst -*-
+
+.. _architecture-design:
+
+Design Considerations
+=====================
+
+This section will discuss several aspects of the design of Bcfg2, and the
+particular use cases that motivated them. Initially, this will consist
+of a discussion of the system metadata, and the intended usage model
+for package indices as well.
+
+System Metadata
+---------------
+
+Bcfg2 system metadata describes the underlying patterns in system
+configurations. It describes commonalities and differences between these
+specifications in a rigorous way. The groups used by Bcfg2's metadata are
+responsible for differentiating clients from one another, and building
+collections of allocatable configuration.
+
+The Bcfg2 metadata system has been designed with several high-level
+goals in mind. Flexibility and precision are paramount concerns; no
+configuration should be undescribable using the constructs present in
+the Bcfg2 repository. We have found (generally the hard way) that any
+assumptions about the inherent simplicity of configuration patterns tend
+to be wrong, so obscenely complex configurations must be representable,
+even if these requirements seem illogical during the implementation.
+
+In particular, we wanted to streamline several operations that commonly
+occurred in our environment.
+
+* Copying one node's profile to another node.
+
+  In many environments, many nodes are instances of a common configuration
+  specification. They all have similar roles and software. In our
+  environment, desktop machines were the best example of this. Other than
+  strictly per-host configuration like SSH keys, all desktop machines
+  use a common configuration specification. This trivializes the process
+  of creating a new desktop machine.
+
+* Creating a specialized version of an existing profile.
+
+  In environments with highly varied configurations, departmental
+  infrastructure being a good example, "another machine like X but with
+  extra software" is a common requirement. For this reason, it must be
+  trivially possible to inherit most of a configuration specification
+  from  some more generic source, while being able to describe overriding
+  aspects in a convenient fashion.
+
+* Compose several pre-existing configuration aspects to create a new profile.
+
+  The ability to compose configuration aspects allows the easy creation
+  of new profiles based on a series of predefined set of configuration
+  specification fragments. The end result is more agility in environments
+  where change is the norm.
+
+  In order for a classing system to be comprehensive, it must be usable in
+  complex ways. The Bcfg2 metadata system has constructs that map cleanly
+  to first-order logic. This implies that any complex configuration
+  pattern can be represented (at all) by the metadata, as first-order
+  logic is provably comprehensive.  (There is a discussion later in the
+  document describing the metadata system in detail, and showing how it
+  corresponds to first-order logic)
+
+These use cases motivate several of the design decisions that we
+made. There must be a many to one correspondence between clients and
+groups. Membership in a given profile group must imbue a client with
+all of its configuration properties.
+
+Package Management
+------------------
+
+The interface provided in the Bcfg2 repository for package specification
+was designed with automation in mind. The goal was to support an
+append only interface to the repository, so that users do not need to
+continuously re-write already existing bits of specification.