← Back to branch summary

~nskaggs/+junk/xenial-test

« back to all changes in this revision

Viewing changes to src/github.com/juju/juju/doc/death-and-destruction.txt

  • Committer: Nicholas Skaggs
  • Date: 2016-10-24 20:56:05 UTC
  • Revision ID: nicholas.skaggs@canonical.com-20161024205605-z8lta0uvuhtxwzwl
Initi with beta15

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/github.com/juju/juju/doc/death-and-destruction.txt
 
1
Death and Destruction
 
2
=====================
 
3
 
 
4
This document describes in detail the operations associated with the destruction
 
5
and removal of the fundamental state entities, and what agents are responsible
 
6
for those operations.
 
7
 
 
8
Each entity has an associated destroy-* command. The precise implications of
 
9
destruction differ by entity, but there are common features:
 
10
 
 
11
  * Only Alive entities can be destroyed; if destruction is already in progress,
 
12
    as evidenced by an entity not being Alive, its "destruction" is a no-op.
 
13
  * Entities might be removed immediately when they are destroyed, but this is not
 
14
    guaranteed.
 
15
  * If an entity is not removed immediately when it is destroyed, its eventual
 
16
    removal is very likely; but it is not currently guaranteed, for the
 
17
    following reasons:
 
18
      * Hardware failure, even when detected and corrected by a Provisioner, can
 
19
        lead to unremovable relations, because the redeployed unit doesn't know
 
20
        what relations it's in. This would be fixable by making the unit agent
 
21
        always leave the scope of relations when they're detected; or, probably
 
22
        better, by using actual remote scope membership state to track relation
 
23
        membership (rather than using the existence of a local directory, whose
 
24
        true intent is to track the membership of *other* units, as a proxy).
 
25
        This is actually a pretty serious BUG and should be addressed soon;
 
26
        neither proposed solution is very challenging.
 
27
      * Undetected hardware failure is annoying, and can block progress at any
 
28
        time, but can be observed via additional monitoring and resolved via out-
 
29
        of-band termination of borked resources, which should be sufficient to
 
30
        get the system moving again (assuming the above bug is fixed).
 
31
      * Unknown problems in juju, in which agents fail to fulfil the duties laid
 
32
        out in this document, could block progress at any time. Assuming a
 
33
        version of the agent code which does not exhibit the problem exists, it
 
34
        should always be possible to work around this situation by upgrading the
 
35
        agent; and, if that fails, by terminating the underlying provider
 
36
        resources out-of-band, as above, and waiting for the new agent version
 
37
        to be deployed on a fresh system (with the same caveat as above).
 
38
      * In light of the preceding two points, we don't *have* to implement
 
39
        "--force" options for `juju destroy-machine` and `juju destroy-unit`.
 
40
        This is good, because it will be tricky to implement them well.
 
41
 
 
42
In general, the user can just forget about entities once she's destroyed them;
 
43
the only caveat is that she may not create new services with the same name, or
 
44
new relations identical to the destroyed ones, until those entities have
 
45
finally been removed.
 
46
 
 
47
In rough order of complexity, here's what happens when each entity kind is
 
48
destroyed. Note that in general the appropriate action is contingent on
 
49
mutable remote state, and many operations must be expressed as a transaction
 
50
involving several documents: the state API must be prepared to handle aborted
 
51
transactions and either diagnose definite failure or retry until the operation
 
52
succeeds (or, perhaps, finally error out pleading excessive contention).
 
53
 
 
54
 
 
55
juju destroy-machine
 
56
--------------------
 
57
 
 
58
Destroying a machine involves a single transaction defined as follows:
 
59
 
 
60
  * If the machine is not Alive, abort without error.
 
61
  * If the machine is the last one with JobManageModel, or has any assigned
 
62
    units, abort with an appropriate error.
 
63
  * Set the machine to Dying.
 
64
 
 
65
When a machine becomes Dying, the following operation occurs:
 
66
 
 
67
  * The machine's agent sets the machine to Dead.
 
68
 
 
69
When a machine becomes Dead, the following operations occur:
 
70
 
 
71
  * The machine's agent terminates itself and refuses to run again.
 
72
  * A Provisioner (a task running in some other machine agent) observes the
 
73
    death, decommissions the machine's resources, and removes the machine.
 
74
 
 
75
Removing a machine involves a single transaction defined as follows:
 
76
 
 
77
  * If the machine is not Dead, abort with an appropriate error.
 
78
  * Delete the machine document.
 
79
 
 
80
 
 
81
juju destroy-unit
 
82
-----------------
 
83
 
 
84
Destroying a unit involves a single transaction defined as follows:
 
85
 
 
86
  * If the unit is not Alive, abort without error.
 
87
  * Set the unit to Dying.
 
88
 
 
89
When a unit becomes Dying, the following operations occur:
 
90
 
 
91
  * The unit's agent leaves the scopes of all its relations. Note that this is
 
92
    a potentially complex sequence of operations and may take some time; in
 
93
    particular, any hooks that fail while the unit is leaving relations and
 
94
    stopping the charm will suspend this sequence until resolved (just like
 
95
    when the unit is Alive).
 
96
  * The unit's agent then sets the unit to Dead.
 
97
 
 
98
When a unit becomes Dead, the following operations occur:
 
99
 
 
100
  * The unit's agent terminates itself and refuses to run again.
 
101
  * The agent of the entity that deployed the unit (that is: a machine agent,
 
102
    for a principal unit; or, for a subordinate unit, the agent of a principal
 
103
    unit) observes the death, recalls the unit, and removes it.
 
104
 
 
105
Removing a unit involves a single transaction, defined as follows:
 
106
 
 
107
  * If the unit is a principal unit, unassign the unit from its machine.
 
108
  * If the unit is a subordinate unit, unassign it from its principal unit.
 
109
  * Delete the unit document.
 
110
  * If its service is Alive, or has at least two units, or is in at least
 
111
    one relation, decrement the service's unit count; otherwise remove the
 
112
    service.
 
113
 
 
114
 
 
115
juju destroy-relation
 
116
---------------------
 
117
 
 
118
Destroying a relation involves a single transaction defined as follows:
 
119
 
 
120
  * If the relation is not Alive, abort without error.
 
121
  * If any unit is in scope, set the relation to Dying.
 
122
  * Otherwise:
 
123
      * If the relation destruction is a direct user request, decrement the
 
124
        relation counts of both services.
 
125
      * If the relation destruction is an immediate consequence of service
 
126
        destruction, decrement the reference count of the counterpart service
 
127
        alone. (This is because the service destruction logic is responsible
 
128
        for the relation count of the service being destroyed.)
 
129
      * Delete the relation document.
 
130
      * Mark the relation's unit settings documents for future cleanup.
 
131
          * This is done by creating a single document for the attention of
 
132
            some other part of the system (BUG: which doesn't exist), that is
 
133
            then responsible for mass-deleting the (potentially large number
 
134
            of) settings documents. This completely bypasses the mgo/txn
 
135
            mechanism, but we don't care because those documents are guaranteed
 
136
            to be unreferenced and unwatched, by virtue of the relation's prior
 
137
            removal.
 
138
 
 
139
When a relation is set to Dying, the following operations occur:
 
140
 
 
141
  * Every unit agent whose unit has entered the scope of that relation
 
142
    observes the change and causes its unit to leave scope.
 
143
  * If the relation has container scope, and no other container-scoped relation
 
144
    between its services is Alive, the unit agents of the subordinate units in
 
145
    the relation will observe the change and destroy their units.
 
146
 
 
147
The Dying relation's document is finally removed in the same transaction in
 
148
which the last unit leaves its scope. Because this situation involves the
 
149
relation already being Dying, its services may also be Dying, and so the
 
150
operations involved are subtly different to those taken above (when we know
 
151
for sure that the relation -- and hence both services -- are still Alive).
 
152
 
 
153
  * Here, "the service" refers to the service of the unit departing scope, and
 
154
    "the counterpart service" refers to the other service in the relation.
 
155
  * Decrement the relation count of the unit's service (we know that service
 
156
    is not ready to be removed, because its unit is responsible for this
 
157
    transaction and the service clearly therefore has a unit count greater
 
158
    than zero).
 
159
  * Delete the relation document.
 
160
  * Mark the relation's unit settings documents for future cleanup.
 
161
  * If the counterpart service (the one that is not the unit's service) is
 
162
    Alive, or has at least one unit, or is in at least two relations, decrement
 
163
    its relation count; otherwise remove the counterpart service.
 
164
 
 
165
 
 
166
juju destroy-service
 
167
--------------------
 
168
 
 
169
Destroying a service involves a single transaction defined as follows:
 
170
 
 
171
  * If the application is not alive, abort without error.
 
172
  * If the service is in any relations, do the following for each one:
 
173
      * If the relation is already Dying, skip it.
 
174
      * If the relation is Alive, destroy the relation without modifying the
 
175
        service's relation count. If the relation's destruction implies its
 
176
        removal, increment a local removed-relations counter instead.
 
177
  * If the service's unit count is greater than 0, or if the value of the
 
178
    aforementioned removal counter is less than the service's relation count,
 
179
    we know that some entity will still hold a reference to the service after
 
180
    the transaction completes, so we set the service to Dying and decrement
 
181
    its relation count by the value of the removal counter.
 
182
  * Otherwise, remove the service immediately, because we know that no
 
183
    reference to the service will survive the transaction.
 
184
 
 
185
When a service becomes Dying, the following operations occur:
 
186
 
 
187
  * Every unit agent of the service observes the change and destroys its unit.
 
188
 
 
189
The Dying service's document is finally removed in the same transaction that
 
190
removes the last entity referencing that service. This could be either the
 
191
removal of the last unit in the service, or the removal of the last relation
 
192
the service is in, as described above. To remove a service, the following
 
193
operations must occur in a single transaction:
 
194
 
 
195
  * Remove the service document.
 
196
  * Remove the service's settings document.