![[bottom]](../icons/bottom.png){kind=icon}
![[previous]](../icons/n_left.png){kind=icon}
![[next]](../icons/n_right.png){kind=icon}
![[first]](../icons/n_first.png){kind=icon}
![[last]](../icons/n_last.png){kind=icon}
![[top]](../icons/n_top.png){kind=icon}
![[index]](../icons/index.png){kind=icon}
![[help]](../icons/help.png){kind=icon}
*/
1 /*
2 * Copyright 2004-2024 the Pacemaker project contributors
3 *
4 * The version control history for this file may have further details.
5 *
6 * This source code is licensed under the GNU Lesser General Public License
7 * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
8 */
9
10 #ifndef PCMK__CRM_COMMON_ACTIONS__H
11 #define PCMK__CRM_COMMON_ACTIONS__H
12
13 #include <stdbool.h> // bool
14 #include <strings.h> // strcasecmp()
15 #include <glib.h> // gboolean, guint
16 #include <libxml/tree.h> // xmlNode
17
18 #include <crm/lrmd_events.h> // lrmd_event_data_t
19
20 #include <glib.h> // GList, GHashTable
21 #include <libxml/tree.h> // xmlNode
22
23 #include <crm/common/nodes.h>
24 #include <crm/common/resources.h> // enum rsc_start_requirement, etc.
25 #include <crm/common/scheduler_types.h> // pcmk_resource_t, pcmk_node_t
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 /*!
32 * \file
33 * \brief APIs related to actions
34 * \ingroup core
35 */
36
37 //! Default timeout (in milliseconds) for non-metadata actions
38 #define PCMK_DEFAULT_ACTION_TIMEOUT_MS 20000
39
40 // @COMPAT We don't need a separate timeout for metadata, much less a longer one
41 //! \deprecated Default timeout (in milliseconds) for metadata actions
42 #define PCMK_DEFAULT_METADATA_TIMEOUT_MS 30000
43
44 // Action names as strings
45 #define PCMK_ACTION_CANCEL "cancel"
46 #define PCMK_ACTION_CLEAR_FAILCOUNT "clear_failcount"
47 #define PCMK_ACTION_CLONE_ONE_OR_MORE "clone-one-or-more"
48 #define PCMK_ACTION_DELETE "delete"
49 #define PCMK_ACTION_DEMOTE "demote"
50 #define PCMK_ACTION_DEMOTED "demoted"
51 #define PCMK_ACTION_DO_SHUTDOWN "do_shutdown"
52 #define PCMK_ACTION_LIST "list"
53 #define PCMK_ACTION_LRM_DELETE "lrm_delete"
54 #define PCMK_ACTION_LOAD_STOPPED "load_stopped"
55 #define PCMK_ACTION_MAINTENANCE_NODES "maintenance_nodes"
56 #define PCMK_ACTION_META_DATA "meta-data"
57 #define PCMK_ACTION_METADATA "metadata"
58 #define PCMK_ACTION_MIGRATE_FROM "migrate_from"
59 #define PCMK_ACTION_MIGRATE_TO "migrate_to"
60 #define PCMK_ACTION_MONITOR "monitor"
61 #define PCMK_ACTION_NOTIFIED "notified"
62 #define PCMK_ACTION_NOTIFY "notify"
63 #define PCMK_ACTION_OFF "off"
64 #define PCMK_ACTION_ON "on"
65 #define PCMK_ACTION_ONE_OR_MORE "one-or-more"
66 #define PCMK_ACTION_PROMOTE "promote"
67 #define PCMK_ACTION_PROMOTED "promoted"
68 #define PCMK_ACTION_REBOOT "reboot"
69 #define PCMK_ACTION_RELOAD "reload"
70 #define PCMK_ACTION_RELOAD_AGENT "reload-agent"
71 #define PCMK_ACTION_RUNNING "running"
72 #define PCMK_ACTION_START "start"
73 #define PCMK_ACTION_STATUS "status"
74 #define PCMK_ACTION_STONITH "stonith"
75 #define PCMK_ACTION_STOP "stop"
76 #define PCMK_ACTION_STOPPED "stopped"
77 #define PCMK_ACTION_VALIDATE_ALL "validate-all"
78
79 // Possible actions (including some pseudo-actions)
80 // @COMPAT Make this internal when we can break API backward compatibility
81 //!@{
82 //! \deprecated Do not use (public access will be removed in a future release)
83 enum action_tasks {
84 pcmk_action_unspecified = 0, // Unspecified or unknown action
85 pcmk_action_monitor, // Monitor
86
87 // Each "completed" action must be the regular action plus 1
88
89 pcmk_action_stop, // Stop
90 pcmk_action_stopped, // Stop completed
91
92 pcmk_action_start, // Start
93 pcmk_action_started, // Start completed
94
95 pcmk_action_notify, // Notify
96 pcmk_action_notified, // Notify completed
97
98 pcmk_action_promote, // Promote
99 pcmk_action_promoted, // Promoted
100
101 pcmk_action_demote, // Demote
102 pcmk_action_demoted, // Demoted
103
104 pcmk_action_shutdown, // Shut down node
105 pcmk_action_fence, // Fence node
106
107 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
108 no_action = pcmk_action_unspecified,
109 monitor_rsc = pcmk_action_monitor,
110 stop_rsc = pcmk_action_stop,
111 stopped_rsc = pcmk_action_stopped,
112 start_rsc = pcmk_action_start,
113 started_rsc = pcmk_action_started,
114 action_notify = pcmk_action_notify,
115 action_notified = pcmk_action_notified,
116 action_promote = pcmk_action_promote,
117 action_promoted = pcmk_action_promoted,
118 action_demote = pcmk_action_demote,
119 action_demoted = pcmk_action_demoted,
120 shutdown_crm = pcmk_action_shutdown,
121 stonith_node = pcmk_action_fence,
122 #endif
123 };
124 //!@}
125
126 // Possible responses to a resource action failure
127 // @COMPAT Make this internal when we can break API backward compatibility
128 //!@{
129 //! \deprecated Do not use (public access will be removed in a future release)
130 enum action_fail_response {
131 /* The order is (partially) significant here; the values from
132 * pcmk_on_fail_ignore through pcmk_on_fail_fence_node are in order of
133 * increasing severity.
134 *
135 * @COMPAT The values should be ordered and numbered per the "TODO" comments
136 * below, so all values are in order of severity and there is room for
137 * future additions, but that would break API compatibility.
138 * @TODO For now, we just use a function to compare the values specially, but
139 * at the next compatibility break, we should arrange things
140 * properly so we can compare with less than and greater than.
141 */
142
143 // @TODO Define as 10
144 pcmk_on_fail_ignore = 0, // Act as if failure didn't happen
145
146 // @TODO Define as 30
147 pcmk_on_fail_restart = 1, // Restart resource
148
149 // @TODO Define as 60
150 pcmk_on_fail_ban = 2, // Ban resource from current node
151
152 // @TODO Define as 70
153 pcmk_on_fail_block = 3, // Treat resource as unmanaged
154
155 // @TODO Define as 80
156 pcmk_on_fail_stop = 4, // Stop resource and leave stopped
157
158 // @TODO Define as 90
159 pcmk_on_fail_standby_node = 5, // Put resource's node in standby
160
161 // @TODO Define as 100
162 pcmk_on_fail_fence_node = 6, // Fence resource's node
163
164 // @COMPAT Values below here are out of desired order for API compatibility
165
166 // @TODO Define as 50
167 pcmk_on_fail_restart_container = 7, // Restart resource's container
168
169 // @TODO Define as 40
170 /*
171 * Fence the remote node created by the resource if fencing is enabled,
172 * otherwise attempt to restart the resource (used internally for some
173 * remote connection failures).
174 */
175 pcmk_on_fail_reset_remote = 8,
176
177 // @TODO Define as 20
178 pcmk_on_fail_demote = 9, // Demote if promotable, else stop
179
180 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
181 action_fail_ignore = pcmk_on_fail_ignore,
182 action_fail_recover = pcmk_on_fail_restart,
183 action_fail_migrate = pcmk_on_fail_ban,
184 action_fail_block = pcmk_on_fail_block,
185 action_fail_stop = pcmk_on_fail_stop,
186 action_fail_standby = pcmk_on_fail_standby_node,
187 action_fail_fence = pcmk_on_fail_fence_node,
188 action_fail_restart_container = pcmk_on_fail_restart_container,
189 action_fail_reset_remote = pcmk_on_fail_reset_remote,
190 action_fail_demote = pcmk_on_fail_demote,
191 #endif
192 };
193 //!@}
194
195 // Action scheduling flags
196 // @COMPAT Make this internal when we can break API backward compatibility
197 //!@{
198 //! \deprecated Do not use (public access will be removed in a future release)
199 enum pe_action_flags {
200 // No action flags set (compare with equality rather than bit set)
201 pcmk_no_action_flags = 0,
202
203 // Whether action does not require invoking an agent
204 pcmk_action_pseudo = (1 << 0),
205
206 // Whether action is runnable
207 pcmk_action_runnable = (1 << 1),
208
209 // Whether action should not be executed
210 pcmk_action_optional = (1 << 2),
211
212 // Whether action should be added to transition graph even if optional
213 pcmk_action_always_in_graph = (1 << 3),
214
215 // Whether operation-specific instance attributes have been unpacked yet
216 pcmk_action_attrs_evaluated = (1 << 4),
217
218 // Whether action is allowed to be part of a live migration
219 pcmk_action_migratable = (1 << 7),
220
221 // Whether action has been added to transition graph
222 pcmk_action_added_to_graph = (1 << 8),
223
224 // Whether action is a stop to abort a dangling migration
225 pcmk_action_migration_abort = (1 << 11),
226
227 /*
228 * Whether action is an ordering point for minimum required instances
229 * (used to implement ordering after clones with \c PCMK_META_CLONE_MIN
230 * configured, and ordered sets with \c PCMK_XA_REQUIRE_ALL set to
231 * \c PCMK_VALUE_FALSE).
232 */
233 pcmk_action_min_runnable = (1 << 12),
234
235 // Whether action is recurring monitor that must be rescheduled if active
236 pcmk_action_reschedule = (1 << 13),
237
238 // Whether action has already been processed by a recursive procedure
239 pcmk_action_detect_loop = (1 << 14),
240
241 // Whether action's inputs have been de-duplicated yet
242 pcmk_action_inputs_deduplicated = (1 << 15),
243
244 // Whether action can be executed on DC rather than own node
245 pcmk_action_on_dc = (1 << 16),
246
247 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
248 pe_action_pseudo = pcmk_action_pseudo,
249 pe_action_runnable = pcmk_action_runnable,
250 pe_action_optional = pcmk_action_optional,
251 pe_action_print_always = pcmk_action_always_in_graph,
252 pe_action_have_node_attrs = pcmk_action_attrs_evaluated,
253 pe_action_implied_by_stonith = (1 << 6),
254 pe_action_migrate_runnable = pcmk_action_migratable,
255 pe_action_dumped = pcmk_action_added_to_graph,
256 pe_action_processed = (1 << 9),
257 pe_action_clear = (1 << 10),
258 pe_action_dangle = pcmk_action_migration_abort,
259 pe_action_requires_any = pcmk_action_min_runnable,
260 pe_action_reschedule = pcmk_action_reschedule,
261 pe_action_tracking = pcmk_action_detect_loop,
262 pe_action_dedup = pcmk_action_inputs_deduplicated,
263 pe_action_dc = pcmk_action_on_dc,
264 #endif
265 };
266 //!@}
267
268 /* @COMPAT enum pe_link_state and enum pe_ordering are currently needed for
269 * struct pe_action_wrapper_s (which is public) but should be removed at an
270 * API compatibility break when that can be refactored and made internal
271 */
272
273 //!@{
274 //! \deprecated Do not use
275 enum pe_link_state {
276 pe_link_not_dumped = 0,
277 pe_link_dumped = 1,
278 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
279 pe_link_dup = 2,
280 #endif
281 };
282
283 enum pe_ordering {
284 pe_order_none = 0x0,
285 #if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
286 pe_order_optional = 0x1,
287 pe_order_apply_first_non_migratable = 0x2,
288 pe_order_implies_first = 0x10,
289 pe_order_implies_then = 0x20,
290 pe_order_promoted_implies_first = 0x40,
291 pe_order_implies_first_migratable = 0x80,
292 pe_order_runnable_left = 0x100,
293 pe_order_pseudo_left = 0x200,
294 pe_order_implies_then_on_node = 0x400,
295 pe_order_probe = 0x800,
296 pe_order_restart = 0x1000,
297 pe_order_stonith_stop = 0x2000,
298 pe_order_serialize_only = 0x4000,
299 pe_order_same_node = 0x8000,
300 pe_order_implies_first_printed = 0x10000,
301 pe_order_implies_then_printed = 0x20000,
302 pe_order_asymmetrical = 0x100000,
303 pe_order_load = 0x200000,
304 pe_order_one_or_more = 0x400000,
305 pe_order_anti_colocation = 0x800000,
306 pe_order_preserve = 0x1000000,
307 pe_order_then_cancels_first = 0x2000000,
308 pe_order_trace = 0x4000000,
309 pe_order_implies_first_master = pe_order_promoted_implies_first,
310 #endif
311 };
312
313 // Action sequenced relative to another action
314 // @COMPAT This should be internal
315 struct pe_action_wrapper_s {
316 // @COMPAT This should be uint32_t
317 enum pe_ordering type; // Group of enum pcmk__action_relation_flags
318
319 // @COMPAT This should be a bool
320 enum pe_link_state state; // Whether action has been added to graph yet
321
322 pcmk_action_t *action; // Action to be sequenced
323 };
324 //!@}
325
326 // Implementation of pcmk_action_t
327 // @COMPAT Make this internal when we can break API backward compatibility
328 //!@{
329 //! \deprecated Do not use (public access will be removed in a future release)
330 struct pe_action_s {
331 int id; // Counter to identify action
332
333 /*
334 * When the controller aborts a transition graph, it sets an abort priority.
335 * If this priority is higher, the action will still be executed anyway.
336 * Pseudo-actions are always allowed, so this is irrelevant for them.
337 */
338 int priority;
339
340 pcmk_resource_t *rsc; // Resource to apply action to, if any
341 pcmk_node_t *node; // Node to execute action on, if any
342 xmlNode *op_entry; // Action XML configuration, if any
343 char *task; // Action name
344 char *uuid; // Action key
345 char *cancel_task; // If task is "cancel", the action being cancelled
346 char *reason; // Readable description of why action is needed
347
348 //@ COMPAT Change to uint32_t at a compatibility break
349 enum pe_action_flags flags; // Group of enum pe_action_flags
350
351 enum rsc_start_requirement needs; // Prerequisite for recovery
352 enum action_fail_response on_fail; // Response to failure
353 enum rsc_role_e fail_role; // Resource role if action fails
354 GHashTable *meta; // Meta-attributes relevant to action
355 GHashTable *extra; // Action-specific instance attributes
356
357 /* Current count of runnable instance actions for "first" action in an
358 * ordering dependency with pcmk__ar_min_runnable set.
359 */
360 int runnable_before; // For Pacemaker use only
361
362 /*
363 * Number of instance actions for "first" action in an ordering dependency
364 * with pcmk__ar_min_runnable set that must be runnable before this action
365 * can be runnable.
366 */
367 int required_runnable_before;
368
369 // Actions in a relation with this one (as pcmk__related_action_t *)
370 GList *actions_before;
371 GList *actions_after;
372
373 /* This is intended to hold data that varies by the type of action, but is
374 * not currently used. Some of the above fields could be moved here except
375 * for API backward compatibility.
376 */
377 void *action_details;
378 };
379 //!@}
380
381 // @COMPAT Make this internal when we can break API backward compatibility
382 //! \deprecated Do not use (public access will be removed in a future release)
383 const char *pcmk_action_text(enum action_tasks action);
384
385 // @COMPAT Make this internal when we can break API backward compatibility
386 //! \deprecated Do not use (public access will be removed in a future release)
387 enum action_tasks pcmk_parse_action(const char *action_name);
388
389 // @COMPAT Make this internal when we can break API backward compatibility
390 //! \deprecated Do not use (public access will be removed in a future release)
391 const char *pcmk_on_fail_text(enum action_fail_response on_fail);
392
393 // For parsing various action-related string specifications
394 gboolean parse_op_key(const char *key, char **rsc_id, char **op_type,
395 guint *interval_ms);
396 gboolean decode_transition_key(const char *key, char **uuid, int *transition_id,
397 int *action_id, int *target_rc);
398 gboolean decode_transition_magic(const char *magic, char **uuid,
399 int *transition_id, int *action_id,
400 int *op_status, int *op_rc, int *target_rc);
401
402 // @COMPAT Either these shouldn't be in libcrmcommon or lrmd_event_data_t should
403 int rsc_op_expected_rc(const lrmd_event_data_t *event);
404 gboolean did_rsc_op_fail(lrmd_event_data_t *event, int target_rc);
405
406 bool crm_op_needs_metadata(const char *rsc_class, const char *op);
407
408 xmlNode *crm_create_op_xml(xmlNode *parent, const char *prefix,
409 const char *task, const char *interval_spec,
410 const char *timeout);
411
412 bool pcmk_is_probe(const char *task, guint interval);
413 bool pcmk_xe_is_probe(const xmlNode *xml_op);
414 bool pcmk_xe_mask_probe_failure(const xmlNode *xml_op);
415
416 #ifdef __cplusplus
417 }
418 #endif
419
420 #endif // PCMK__CRM_COMMON_ACTIONS__H
![[top]](../icons/top.png){kind=icon}
![[bottom]](../icons/n_bottom.png){kind=icon}
*/