summaryrefslogtreecommitdiffstats
path: root/docs/proposals/playbook_consolidation.md
blob: 98aedb021e6f02b3e18cf0b074568af00ae8025e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
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