Merge pull request #246 from twiest/pr

Added concepts guide.

3 files changed, 43 insertions, 1 deletions

diff --git a/docs/best_practices.adoc b/docs/best_practices_guide.adoc
index 938b6b46a..938b6b46a 100644
--- a/docs/best_practices.adoc
+++ b/docs/best_practices_guide.adoc
diff --git a/docs/core_concepts_guide.adoc b/docs/core_concepts_guide.adoc
new file mode 100644
index 000000000..0d746bfb5
--- /dev/null
+++ b/docs/core_concepts_guide.adoc
@@ -0,0 +1,42 @@
+// vim: ft=asciidoc
+
+= Openshift-Ansible Core Concepts Guide
+
+The purpose of this guide is to describe core concepts used in this repository.
+
+It is important to note that this repository may not currently implement all of the concepts, but our intention is that it will.
+
+== Logical Grouping Concepts
+The following are the concepts we use to logically group OpenShift cluster instances.
+
+We use these groupings to perform operations specifically against instances in the specified group.
+
+For example, run an Ansible playbook against all instances in the `production` environment, or run an adhoc command against all instances in the `acme-corp` cluster group.
+
+=== Cluster
+A Cluster is a complete install of OpenShift (master, nodes, registry, router, etc).
+
+Example: Acme Corp has sales and marketing departments that both want to use OpenShift for their internal applications, but they do not want to share resources because they have different cost centers. Each department could have their own completely separate install of OpenShift. Each install is a separate OpenShift cluster.
+
+Defined Clusters:
+`acme-sales`
+`acme-marketing`
+
+=== Cluster Group
+A cluster group is a logical grouping of one or more clusters. Which clusters are in which cluster groups is determined by the OpenShift administrators.
+
+Example: Extending the example above, both marketing and sales clusters are part of Acme Corp. Let's say that Acme Corp contracts with Hosting Corp to host their OpenShift clusters. Hosting Corp could create an Acme Corp cluster group.
+
+This would logically group Acme Corp resources from other Hosting Corp customers, which would enable the Hosting Corp's OpenShift administrators to run operations specifically targeting Acme Corp instances.
+
+Defined Cluster Group:
+`acme-corp`
+
+=== Environment
+An environment is a logical grouping of one or more cluster groups. How the environment is defined is determined by the OpenShift administrators.
+
+Example: Extending the two examples above, Hosting Corp could provide both production and staging environments for it's customers. In this way, Acme Corp could push their code to the staging environment and test it out before pushing it to production.
+
+Defined Environments:
+`production`
+`staging`
diff --git a/docs/style_guide.adoc b/docs/style_guide.adoc
index 26a8c4636..714b56c70 100644
--- a/docs/style_guide.adoc
+++ b/docs/style_guide.adoc
@@ -1,7 +1,7 @@
 // vim: ft=asciidoc
 
 = Openshift-Ansible Style Guide
------------------------------
+
 The purpose of this guide is to describe the preferred coding conventions used in this repository (both in ansible and python).
 
 It is important to note that this repository may not currently comply with all style guide rules, but our intention is that it will.