Skip to content

Commit a92c3c7

Browse files
wmudgewmudge
authored
Add api-design.md write up (#277)
Signed-off-by: Webster Mudge <[email protected]>
1 parent 3cb3731 commit a92c3c7

File tree

1 file changed

+236
-0
lines changed

1 file changed

+236
-0
lines changed

‎docs/api-design.md‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
# cloudera.cluster API Design
2+
3+
One of the core tenants of the `cloudera.cluster` modules is the management of _role assignments_. That is, a role assignment represents the application of a given service's code to an individual cluster host.
4+
5+
From the perspective of the modules' API, assignments are handled according to the scope of the enclosing entity module, e.g. `service`, `role`, and `host`. In addition, the `host_template` module handles indirect assignment via the implicit `role` associate of each `role_config_group`.
6+
7+
The sections below illustrate the scope of assignments and configuration management for each entity.
8+
9+
# Cluster
10+
11+
Within the *Cluster* module, the order of precedence for a Role assignment to a cluster Host is the following:
12+
13+
1. `type` assignment within `service.roles` (direct)
14+
2. `type` assignment within `hosts.roles` (direct)
15+
3. `role_config_group` assignment within `service.roles` (indirect)
16+
4. `name` or `type` assignment within `hosts.role_config_groups` (indirect)
17+
5. `host_template` assignment within `hosts.host_template` (indirect)
18+
19+
Note that Role Config Groups are _defined_ only within `service.role_config_groups`, and Host Templates are _defined_ only within `host_templates`; both are _assigned_ in other parameters.
20+
21+
```yaml
22+
cloudera.cluster.cluster:
23+
name: # str
24+
display_name: # str
25+
version: # str
26+
type: # enumeration
27+
state: # enumeration
28+
template: # json
29+
repos_appended: # bool
30+
parcels: # list[str]
31+
tags: # dict
32+
contexts: # list[str]
33+
tls_enabled: # bool
34+
auto_assignment_enabled: # bool
35+
maintenance_enabled: # bool
36+
purge: # bool
37+
control_plane:
38+
remote_repo_url: # str
39+
datalake_cluster_name: # str
40+
control_plane_config: # yaml
41+
services:
42+
- name: # str
43+
display_name: # str
44+
type: # enumeration
45+
version: # str
46+
state: # enumeration -- overridden by cluster.state
47+
maintenance_enabled: # bool -- ignored if service.maintenance_enabled is not None
48+
config: # dict
49+
tags: # dict
50+
roles: # Assignment -- see role module
51+
- type: # str
52+
hostnames: # list[str] -- allows for multiple assignment
53+
host_ids: # list[str] -- allows for mulitple assignment
54+
state: # enumeration -- overridden by service
55+
maintenance_enabled: # bool -- ignored if cluster.maintenance_enabled is not None
56+
config: # dict
57+
role_config_group: # str
58+
tags: # dict
59+
role_config_groups: # Definition only
60+
- name: # str
61+
display_name: # str
62+
type: # str
63+
config: # dict
64+
host_templates: # See host_template module
65+
- name: # str
66+
role_config_groups: # Reference-only
67+
- name: # str
68+
type: # str
69+
service: # str
70+
service_type: # str
71+
hosts: # See host module
72+
- hostnames: # list[str] -- allows for multiple assignment
73+
host_ids: # list[str] -- allows for multiple assignment
74+
config: # dict
75+
host_template: # str
76+
role_config_groups: # Reference-only
77+
- service: # str
78+
name: # str
79+
type: # str
80+
roles: # Assignment
81+
- service: # str
82+
type: # str
83+
config: # dict
84+
```
85+
86+
The `purge` flag will affect the following parameters:
87+
88+
- `parcels`
89+
- `tags`
90+
- `contexts`
91+
- `services.config` _(i.e. service-wide configuration)_
92+
- `services.tags`
93+
- `services.roles`
94+
- `services.roles.hostnames`
95+
- `services.roles.host_ids`
96+
- `services.roles.config` _(i.e. per-host role configuration overrides)_
97+
- `services.roles.tags`
98+
- `services.role_config_groups`
99+
- `services.role_config_groups.config` _(i.e. shared role configuration)_
100+
- `host_templates`
101+
- `host_templates.role_config_groups`
102+
- `hosts`
103+
- `hosts.hostnames`
104+
- `hosts.host_ids`
105+
- `hosts.config`
106+
- `hosts.role_config_groups` _(i.e. indirect assignment)_
107+
- `hosts.roles` _(i.e. direct assignment)_
108+
- `hosts.roles.config` _(i.e. direct per-host role configuration overrides)_
109+
110+
# Service
111+
112+
Within the *Service* module, Role assignments are handled directly in the `roles` option. Role Config Groups are simply a definition and have no assignments.
113+
114+
```yaml
115+
cloudera.cluster.service:
116+
name: # str
117+
display_name: # str
118+
type: # enumeration
119+
version: # str
120+
state: # enumeration
121+
maintenance_enabled: # bool
122+
purge: # bool
123+
config: # dict
124+
tags: # dict
125+
roles: # Assignment -- see role module
126+
- type: # str
127+
hostnames: # list[str] -- allows for multiple assignment
128+
host_ids: # list[str] -- allows for mulitple assignment
129+
state: # enumeration -- overridden by service
130+
maintenance_enabled: # bool -- ignored if service.maintenance_enabled is not None
131+
config: # dict
132+
role_config_group: # str
133+
tags: # dict
134+
role_config_groups: # Definition only
135+
- name: # str
136+
display_name: # str
137+
type: # str
138+
config: # dict
139+
```
140+
141+
The `purge` flag will affect the following parameters:
142+
143+
- `config` _(i.e. service-wide configuration)_
144+
- `tags`
145+
- `roles`
146+
- `roles.hostnames`
147+
- `roles.host_ids`
148+
- `roles.config` _(i.e. per-host role configuration overrides)_
149+
- `roles.tags`
150+
- `role_config_groups`
151+
- `role_config_groups.config` _(i.e. shared role configuration)_
152+
153+
# Role
154+
155+
Within the *Role* module, assignment is managed directly for a single Role on an individual Host.
156+
157+
```yaml
158+
cloudera.cluster.role:
159+
name: # str -- Reference-only, as role names are auto-generated
160+
type: # str
161+
cluster_hostname: # str
162+
cluster_host_id: # str
163+
state: # enumeration
164+
maintenance_enabled: # bool
165+
purge: # bool
166+
config: # dict
167+
role_config_group: # str
168+
tags: # dict
169+
```
170+
171+
The `purge` flag will affect the following parameters:
172+
173+
- `config`
174+
- `tags`
175+
176+
# Role Config Group
177+
178+
Within the *Role Config Group* module, there is no Role assignment. The module only manages a single Role Config Group and its configuration.
179+
180+
```yaml
181+
cloudera.cluster.role_config_group:
182+
name: # str
183+
display_name: # str
184+
type: # str
185+
purge: # bool
186+
config: # dict
187+
```
188+
189+
The `purge` flag will affect the following parameters:
190+
191+
- `config`
192+
193+
# Host
194+
195+
Within the *Host* module, assignments are both direct, via the `roles` option, and indirect, via the `role_config_groups` and `host_template` options.
196+
197+
```yaml
198+
cloudera.cluster.host:
199+
name: # str
200+
host_id: # str
201+
config: # dict
202+
host_template: # str
203+
purge: # bool
204+
role_config_groups: # Reference-only
205+
- service: # str
206+
name: # str
207+
type: # str
208+
roles: # Assignment
209+
- service: # str
210+
type: # str
211+
config: # dict
212+
```
213+
214+
The `purge` flag will affect the following parameters:
215+
216+
- `config`
217+
- `role_config_groups`
218+
- `roles`
219+
- `roles.config` _(i.e. per-host role configuration overrides)_
220+
221+
# Host Template
222+
223+
Within the *Host Template* module, there is no Role assignment. The module only manages a single Host Template and its configuration.
224+
225+
```yaml
226+
cloudera.cluster.host_template:
227+
name: # str
228+
role_config_groups: # Reference-only
229+
- name: # str
230+
type: # str
231+
service: # str
232+
service_type: # str
233+
```
234+
235+
The `purge` flag will affect the following parameters:
236+
- `role_config_groups`

0 commit comments

Comments
 (0)