Left: | ||
Right: |
OLD | NEW |
---|---|
(Empty) | |
1 Subordinate service implementation details | |
2 ========================================== | |
3 | |
4 This document explains the implementation of subordinate services. For | |
5 a higher level understanding please refer to the primary :doc:`subordinates | |
6 document <subordinate-services>`. | |
7 | |
8 | |
9 Overview | |
10 -------- | |
11 | |
12 Principal services can have relationships with subordinates. This is | |
13 modeled using a new relation type. This new relation type is used | |
14 exclusively between subordinates and principals and is used to limit | |
15 communication to only service units in the same container. | |
niemeyer
2012/01/19 15:06:18
The container relation type is not specific to pri
| |
16 | |
17 This specialized relation type stores information in zookeeper to keep | |
18 the direct mapping between the unit_ids of its participating | |
19 principals and subordinate units. The new relation type is constructed | |
niemeyer
2012/01/19 15:06:18
This is too vague to be understandable at this sta
| |
20 in response to information about the interfaces on the charms | |
21 involved. | |
22 | |
23 | |
24 Charm changes | |
25 ------------- | |
26 | |
27 Subordinate services are determined by their charm having the setting | |
28 of `container: true` listed in one of their required interfaces. The | |
29 charm's `metadata.yaml` file takes this additional tag as an attribute | |
30 of the interface. `container: true` implies that the interface is | |
31 required, as the charm cannot deploy without this relationship being | |
32 satisfied. :: | |
niemeyer
2012/01/19 15:06:18
Please drop this from this file. This doesn't qual
| |
33 | |
34 requires: | |
35 logging-directory: | |
36 interface: logging | |
37 container: true | |
38 | |
39 | |
40 ZooKeeper State | |
41 --------------- | |
42 | |
43 The new relation type `subordinate-principal` is analogous to | |
44 `client-server` but implemented in such a way that watching only those | |
45 units in the same container is efficient. :: | |
niemeyer
2012/01/19 15:06:18
I don't think we need an entirely new relation typ
| |
46 | |
47 relations: | |
48 relation-00000000: | |
49 settings: | |
50 principal_id-00000001: | |
51 private-address: 10.10.10.101 | |
52 subordinate: subordinate_id-000000002 | |
53 principal_id-00000003: | |
54 private-address: 10.10.10.102 | |
55 subordinate: subordinate_id-000000004 | |
56 | |
57 | |
58 Where each principal node under `settings` is a YAML encoded dict as | |
59 today. This means that each participating node on the principal side | |
60 of the relation will create its UnitRelationState with the id of the | |
61 subordinate in its container clearly mapped under it. | |
62 | |
63 | |
64 | |
65 Watch Related Changes | |
66 --------------------- | |
67 | |
68 The unit agent will use watch_relation_states to see when new | |
69 relations are added. When relations of the `subordinate-principal` | |
70 type are present deployment actions can be taken in the unit agents | |
71 lifecycle. | |
niemeyer
2012/01/19 15:06:18
That's not necessarily the case. If two subordinat
| |
72 | |
73 UnitRelationStates.watch_related_units will dispatch on the new | |
74 relation type and only establish watches between the principal and | |
75 subordinate units in the same container. | |
niemeyer
2012/01/19 15:06:18
This should indeed only fire when appropriate, but
| |
76 | |
77 Deployment | |
78 ---------- | |
79 | |
80 `juju deploy` needs to validate that required interfaces where `container: | |
81 true` and not handle deployments when relationships are not | |
82 satisfied. | |
niemeyer
2012/01/19 15:06:18
Must be adapted.
| |
83 | |
84 The UnitMachineDeployment/UnitContainerDeployment in machine/unit will | |
85 undergo minor refactoring to make it more easily useable by the | |
86 UnitAgent to do its deployment of subordinate services. The Unit Agent | |
87 is the only entity with defined relationships to its subordinates and | |
88 so the UnitAgent does the deployment rather than the | |
89 MachineAgent. This model should continue to work in the expected | |
90 LXCEverywhere future. | |
91 | |
92 When a subordinate unit is deployed it inherits the public and private | |
93 addresses of its principal service (even though it may expose its own | |
94 ports). This is because its network is dependent on the container its | |
95 running it, i.e, that of the principal's service unit. | |
niemeyer
2012/01/19 15:06:18
"inherit" here is making things less clear than th
| |
96 | |
97 One interesting caveat of the current plan is that we don't assign the | |
98 subordinate unit a machine id. `juju-status` below exposes this | |
99 information in a way that is clear and is outlined below. Machine | |
100 assignment is currently used to trigger a class of deployment | |
101 activities which subordinate services do not want to take advantage | |
102 of. | |
niemeyer
2012/01/19 15:06:18
Sounds good. It should probably be an error to att
| |
103 | |
104 `juju.unit.lifecycle._process_service_changes` is currently | |
105 responsible for adding unit state to relations. This code will change | |
106 so that when relationships are added or removed we have access to the | |
107 unit_name of the subordinate. This information is used to annotate the | |
108 UnitRelationState with the mapping from principal unit_name to | |
109 subordinate unit name and is stored in ZooKeeper as outlined | |
110 above. When a relationship is removed we detect this here as well and | |
111 update the mapping using the unit_name of the principal. | |
niemeyer
2012/01/19 15:06:18
I won't review the Python-related changes in detai
| |
112 | |
113 `juju.state.relation.ServiceRelationState.add_unit_state` will be | |
114 augmented to support keeping `subordinate-principal` relations type | |
115 mappings through the addition of an optional `subordinate_unit` | |
116 argument. This will take the `unit_name` of the | |
117 subordinate. | |
niemeyer
2012/01/19 15:06:18
Ditto.
| |
118 | |
119 | |
120 Unit management | |
121 --------------- | |
122 | |
123 `juju add-unit` must raise an error informing the admin they can not | |
124 add units of a subordinate service. These scale automatically with the | |
125 principal service. | |
126 | |
127 `juju remove-unit` produces an error on subordinate services for the | |
128 same reason. | |
129 | |
130 | |
131 Relation Management | |
132 ------------------- | |
133 | |
134 `juju add-relation` and `juju remove-relation` must trigger the | |
135 deployment and removal of subordinate units. This is done using the | |
136 watch machinery outlined above. Each principal service unit will | |
137 deploy a new unit agent for its subordinate when the appropriate new | |
138 relationship is added. | |
niemeyer
2012/01/19 15:06:18
Ditto.
| |
139 | |
140 The subordinate service will maintain a watch of its relationship to | |
141 the principal and should this relationship be removed the subordinate | |
142 will transition its state to stopped and then remove its own state | |
143 from the container and terminate. This will require follow up work to | |
144 handle the proper triggering of stop hooks on the subordinate units | |
145 which isn't handled | |
146 | |
147 Implicit Interfaces | |
148 ------------------- | |
niemeyer
2012/01/19 15:06:18
This section feels a bit confusing given what's ac
bcsaller
2012/01/22 14:27:41
Done.
| |
149 | |
150 Interfaces with `container: true` define required interfaces to the | |
151 principal. Because the principal service may have no special knowledge | |
152 of its subordinates (who may not need or expect any support from the | |
153 principal) we augment the normal relationship matching to include a | |
154 fallback to an implicit `juju-info` interface. When we detect that we | |
niemeyer
2012/01/19 15:06:18
No fallback seems necessary in relation matching.
| |
155 have to supply the `juju-info` interface because no more explicit | |
156 relationship between the subordinate and the principal could be found | |
157 we create a relationship of the new `subordinate-principal` type. | |
158 | |
159 If a service wishes to explicitly related to the `juju-info` interface | |
160 it will use the normal `client-server` relationship type. Support for | |
161 this can be added at a later time however. | |
niemeyer
2012/01/19 15:06:18
The existence of juju-info and subordinate service
bcsaller
2012/01/22 14:27:41
We talked about this on G+ and came to some conclu
| |
162 | |
163 Status | |
164 ------ | |
165 | |
166 The changes to status are outlined in the user oriented documentation. | |
167 | |
168 | |
169 Roadmap | |
170 ------- | |
171 | |
172 This serves as a guide to the planned merge tree. :: | |
173 | |
174 subordinate-spec | |
175 subordinate-charms # (charm metadata support) | |
176 subordinate-implicit-interfaces # (juju-info) | |
177 subordinate-relation-type | |
178 | |
179 subordinate-control-deploy | |
180 subordinate-control-units # (add/remove) | |
181 subordinate-control-status | |
182 | |
183 subordinate-control-relations # (add/remove) | |
184 subordinate-unit-agent-deploy | |
OLD | NEW |