summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/proposals/README.md27
-rw-r--r--docs/proposals/playbook_consolidation.md178
-rw-r--r--docs/proposals/proposal_template.md30
-rw-r--r--docs/repo_structure.md6
4 files changed, 235 insertions, 6 deletions
diff --git a/docs/proposals/README.md b/docs/proposals/README.md
new file mode 100644
index 000000000..89bbe5163
--- /dev/null
+++ b/docs/proposals/README.md
@@ -0,0 +1,27 @@
+# OpenShift-Ansible Proposal Process
+
+## Proposal Decision Tree
+TODO: Add details about when a proposal is or is not required.
+
+## Proposal Process
+The following process should be followed when a proposal is needed:
+
+1. Create a pull request with the initial proposal
+ * Use the [proposal template][template]
+ * Name the proposal using two or three topic words with underscores as a separator (i.e. proposal_template.md)
+ * Place the proposal in the docs/proposals directory
+2. Notify the development team of the proposal and request feedback
+3. Review the proposal on the OpenShift-Ansible Architecture Meeting
+4. Update the proposal as needed and ask for feedback
+5. Approved/Closed Phase
+ * If 75% or more of the active development team give the proposal a :+1: it is Approved
+ * If 50% or more of the active development team disagrees with the proposal it is Closed
+ * If the person proposing the proposal no longer wishes to continue they can request it to be Closed
+ * If there is no activity on a proposal, the active development team may Close the proposal at their discretion
+ * If none of the above is met the cycle can continue to Step 4.
+6. For approved proposals, the current development lead(s) will:
+ * Update the Pull Request with the result and merge the proposal
+ * Create a card on the Cluster Lifecycle [Trello board][trello] so it may be scheduled for implementation.
+
+[template]: proposal_template.md
+[trello]: https://trello.com/b/wJYDst6C
diff --git a/docs/proposals/playbook_consolidation.md b/docs/proposals/playbook_consolidation.md
new file mode 100644
index 000000000..98aedb021
--- /dev/null
+++ b/docs/proposals/playbook_consolidation.md
@@ -0,0 +1,178 @@
+# OpenShift-Ansible Playbook Consolidation
+
+## Description
+The designation of `byo` is no longer applicable due to being able to deploy on
+physical hardware or cloud resources using the playbooks in the `byo` directory.
+Consolidation of these directories will make maintaining the code base easier
+and provide a more straightforward project for users and developers.
+
+The main points of this proposal are:
+* Consolidate initialization playbooks into one set of playbooks in
+ `playbooks/init`.
+* Collapse the `playbooks/byo` and `playbooks/common` into one set of
+ directories at `playbooks/openshift-*`.
+
+This consolidation effort may be more appropriate when the project moves to
+using a container as the default installation method.
+
+## Design
+
+### Initialization Playbook Consolidation
+Currently there are two separate sets of initialization playbooks:
+* `playbooks/byo/openshift-cluster/initialize_groups.yml`
+* `playbooks/common/openshift-cluster/std_include.yml`
+
+Although these playbooks are located in the `openshift-cluster` directory they
+are shared by all of the `openshift-*` areas. These playbooks would be better
+organized in a `playbooks/init` directory collocated with all their related
+playbooks.
+
+In the example below, the following changes have been made:
+* `playbooks/byo/openshift-cluster/initialize_groups.yml` renamed to
+ `playbooks/init/initialize_host_groups.yml`
+* `playbooks/common/openshift-cluster/std_include.yml` renamed to
+ `playbooks/init/main.yml`
+* `- include: playbooks/init/initialize_host_groups.yml` has been added to the
+ top of `playbooks/init/main.yml`
+* All other related files for initialization have been moved to `playbooks/init`
+
+The `initialize_host_groups.yml` playbook is only one play with one task for
+importing variables for inventory group conversions. This task could be further
+consolidated with the play in `evaluate_groups.yml`.
+
+The new standard initialization playbook would be
+`playbooks/init/main.yml`.
+
+
+```
+
+> $ tree openshift-ansible/playbooks/init
+.
+├── evaluate_groups.yml
+├── initialize_facts.yml
+├── initialize_host_groups.yml
+├── initialize_openshift_repos.yml
+├── initialize_openshift_version.yml
+├── main.yml
+├── roles -> ../../roles
+├── validate_hostnames.yml
+└── vars
+ └── cluster_hosts.yml
+```
+
+```yaml
+# openshift-ansible/playbooks/init/main.yml
+---
+- include: initialize_host_groups.yml
+
+- include: evaluate_groups.yml
+
+- include: initialize_facts.yml
+
+- include: validate_hostnames.yml
+
+- include: initialize_openshift_repos.yml
+
+- include: initialize_openshift_version.yml
+```
+
+### `byo` and `common` Playbook Consolidation
+Historically, the `byo` directory coexisted with other platform directories
+which contained playbooks that then called into `common` playbooks to perform
+common installation steps for all platforms. Since the other platform
+directories have been removed this separation is no longer necessary.
+
+In the example below, the following changes have been made:
+* `playbooks/byo/openshift-master` renamed to
+ `playbooks/openshift-master`
+* `playbooks/common/openshift-master` renamed to
+ `playbooks/openshift-master/private`
+* Original `byo` entry point playbooks have been updated to include their
+ respective playbooks from `private/`.
+* Symbolic links have been updated as necessary
+
+All user consumable playbooks are in the root of `openshift-master` and no entry
+point playbooks exist in the `private` directory. Maintaining the separation
+between entry point playbooks and the private playbooks allows individual pieces
+of the deployments to be used as needed by other components.
+
+```
+openshift-ansible/playbooks/openshift-master
+> $ tree
+.
+├── config.yml
+├── private
+│   ├── additional_config.yml
+│   ├── config.yml
+│   ├── filter_plugins -> ../../../filter_plugins
+│   ├── library -> ../../../library
+│   ├── lookup_plugins -> ../../../lookup_plugins
+│   ├── restart_hosts.yml
+│   ├── restart_services.yml
+│   ├── restart.yml
+│   ├── roles -> ../../../roles
+│   ├── scaleup.yml
+│   └── validate_restart.yml
+├── restart.yml
+└── scaleup.yml
+```
+
+```yaml
+# openshift-ansible/playbooks/openshift-master/config.yml
+---
+- include: ../init/main.yml
+
+- include: private/config.yml
+```
+
+With the consolidation of the directory structure and component installs being
+removed from `openshift-cluster`, that directory is no longer necessary. To
+deploy an entire OpenShift cluster, a playbook would be created to tie together
+all of the different components. The following example shows how multiple
+components would be combined to perform a complete install.
+
+```yaml
+# openshift-ansible/playbooks/deploy_cluster.yml
+---
+- include: init/main.yml
+
+- include: openshift-etcd/private/config.yml
+
+- include: openshift-nfs/private/config.yml
+
+- include: openshift-loadbalancer/private/config.yml
+
+- include: openshift-master/private/config.yml
+
+- include: openshift-node/private/config.yml
+
+- include: openshift-glusterfs/private/config.yml
+
+- include: openshift-hosted/private/config.yml
+
+- include: openshift-service-catalog/private/config.yml
+```
+
+## User Story
+As a developer of OpenShift-Ansible,
+I want simplify the playbook directory structure
+so that users can easily find deployment playbooks and developers know where new
+features should be developed.
+
+## Implementation
+Given the size of this refactoring effort, it should be broken into smaller
+steps which can be completed independently while still maintaining a functional
+project.
+
+Steps:
+1. Update and merge consolidation of the initialization playbooks.
+2. Update each merge consolidation of each `openshift-*` component area
+3. Update and merge consolidation of `openshift-cluster`
+
+## Acceptance Criteria
+* Verify that all entry points playbooks install or configure as expected.
+* Verify that CI is updated for testing new playbook locations.
+* Verify that repo documentation is updated
+* Verify that user documentation is updated
+
+## References
diff --git a/docs/proposals/proposal_template.md b/docs/proposals/proposal_template.md
new file mode 100644
index 000000000..ece288037
--- /dev/null
+++ b/docs/proposals/proposal_template.md
@@ -0,0 +1,30 @@
+# Proposal Title
+
+## Description
+<Short introduction>
+
+## Rationale
+<Summary of main points of Design>
+
+## Design
+<Main content goes here>
+
+## Checklist
+* Item 1
+* Item 2
+* Item 3
+
+## User Story
+As a developer on OpenShift-Ansible,
+I want ...
+so that ...
+
+## Acceptance Criteria
+* Verify that ...
+* Verify that ...
+* Verify that ...
+
+## References
+* Link
+* Link
+* Link
diff --git a/docs/repo_structure.md b/docs/repo_structure.md
index f598f22c3..49300f80c 100644
--- a/docs/repo_structure.md
+++ b/docs/repo_structure.md
@@ -28,12 +28,6 @@ These are plugins used in playbooks and roles:
```
.
-├── bin [DEPRECATED] Contains the `bin/cluster` script, a
-│ wrapper around the Ansible playbooks that ensures proper
-│ configuration, and facilitates installing, updating,
-│ destroying and configuring OpenShift clusters.
-│ Note: this tool is kept in the repository for legacy
-│ reasons and will be removed at some point.
└── utils Contains the `atomic-openshift-installer` command, an
interactive CLI utility to install OpenShift across a
set of hosts.