Statistics
| Branch: | Tag: | Revision:

root / lib / opcodes.py @ 57de31c0

History | View | Annotate | Download (51.5 kB)

1
#
2
#
3

    
4
# Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011 Google Inc.
5
#
6
# This program is free software; you can redistribute it and/or modify
7
# it under the terms of the GNU General Public License as published by
8
# the Free Software Foundation; either version 2 of the License, or
9
# (at your option) any later version.
10
#
11
# This program is distributed in the hope that it will be useful, but
12
# WITHOUT ANY WARRANTY; without even the implied warranty of
13
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14
# General Public License for more details.
15
#
16
# You should have received a copy of the GNU General Public License
17
# along with this program; if not, write to the Free Software
18
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19
# 02110-1301, USA.
20

    
21

    
22
"""OpCodes module
23

24
This module implements the data structures which define the cluster
25
operations - the so-called opcodes.
26

27
Every operation which modifies the cluster state is expressed via
28
opcodes.
29

30
"""
31

    
32
# this are practically structures, so disable the message about too
33
# few public methods:
34
# pylint: disable=R0903
35

    
36
import logging
37
import re
38

    
39
from ganeti import compat
40
from ganeti import constants
41
from ganeti import errors
42
from ganeti import ht
43

    
44

    
45
# Common opcode attributes
46

    
47
#: output fields for a query operation
48
_POutputFields = ("output_fields", ht.NoDefault, ht.TListOf(ht.TNonEmptyString),
49
                  "Selected output fields")
50

    
51
#: the shutdown timeout
52
_PShutdownTimeout = \
53
  ("shutdown_timeout", constants.DEFAULT_SHUTDOWN_TIMEOUT, ht.TPositiveInt,
54
   "How long to wait for instance to shut down")
55

    
56
#: the force parameter
57
_PForce = ("force", False, ht.TBool, "Whether to force the operation")
58

    
59
#: a required instance name (for single-instance LUs)
60
_PInstanceName = ("instance_name", ht.NoDefault, ht.TNonEmptyString,
61
                  "Instance name")
62

    
63
#: Whether to ignore offline nodes
64
_PIgnoreOfflineNodes = ("ignore_offline_nodes", False, ht.TBool,
65
                        "Whether to ignore offline nodes")
66

    
67
#: a required node name (for single-node LUs)
68
_PNodeName = ("node_name", ht.NoDefault, ht.TNonEmptyString, "Node name")
69

    
70
#: a required node group name (for single-group LUs)
71
_PGroupName = ("group_name", ht.NoDefault, ht.TNonEmptyString, "Group name")
72

    
73
#: Migration type (live/non-live)
74
_PMigrationMode = ("mode", None,
75
                   ht.TOr(ht.TNone, ht.TElemOf(constants.HT_MIGRATION_MODES)),
76
                   "Migration mode")
77

    
78
#: Obsolete 'live' migration mode (boolean)
79
_PMigrationLive = ("live", None, ht.TMaybeBool,
80
                   "Legacy setting for live migration, do not use")
81

    
82
#: Tag type
83
_PTagKind = ("kind", ht.NoDefault, ht.TElemOf(constants.VALID_TAG_TYPES), None)
84

    
85
#: List of tag strings
86
_PTags = ("tags", ht.NoDefault, ht.TListOf(ht.TNonEmptyString), None)
87

    
88
_PForceVariant = ("force_variant", False, ht.TBool,
89
                  "Whether to force an unknown OS variant")
90

    
91
_PWaitForSync = ("wait_for_sync", True, ht.TBool,
92
                 "Whether to wait for the disk to synchronize")
93

    
94
_PIgnoreConsistency = ("ignore_consistency", False, ht.TBool,
95
                       "Whether to ignore disk consistency")
96

    
97
_PStorageName = ("name", ht.NoDefault, ht.TMaybeString, "Storage name")
98

    
99
_PUseLocking = ("use_locking", False, ht.TBool,
100
                "Whether to use synchronization")
101

    
102
_PNameCheck = ("name_check", True, ht.TBool, "Whether to check name")
103

    
104
_PNodeGroupAllocPolicy = \
105
  ("alloc_policy", None,
106
   ht.TOr(ht.TNone, ht.TElemOf(constants.VALID_ALLOC_POLICIES)),
107
   "Instance allocation policy")
108

    
109
_PGroupNodeParams = ("ndparams", None, ht.TMaybeDict,
110
                     "Default node parameters for group")
111

    
112
_PQueryWhat = ("what", ht.NoDefault, ht.TElemOf(constants.QR_VIA_OP),
113
               "Resource(s) to query for")
114

    
115
_PEarlyRelease = ("early_release", False, ht.TBool,
116
                  "Whether to release locks as soon as possible")
117

    
118
_PIpCheckDoc = "Whether to ensure instance's IP address is inactive"
119

    
120
#: Do not remember instance state changes
121
_PNoRemember = ("no_remember", False, ht.TBool,
122
                "Do not remember the state change")
123

    
124
#: Target node for instance migration/failover
125
_PMigrationTargetNode = ("target_node", None, ht.TMaybeString,
126
                         "Target node for shared-storage instances")
127

    
128
_PStartupPaused = ("startup_paused", False, ht.TBool,
129
                   "Pause instance at startup")
130

    
131
_PVerbose = ("verbose", False, ht.TBool, "Verbose mode")
132

    
133
# Parameters for cluster verification
134
_PDebugSimulateErrors = ("debug_simulate_errors", False, ht.TBool,
135
                         "Whether to simulate errors (useful for debugging)")
136
_PErrorCodes = ("error_codes", False, ht.TBool, "Error codes")
137
_PSkipChecks = ("skip_checks", ht.EmptyList,
138
                ht.TListOf(ht.TElemOf(constants.VERIFY_OPTIONAL_CHECKS)),
139
                "Which checks to skip")
140
_PIgnoreErrors = ("ignore_errors", ht.EmptyList,
141
                  ht.TListOf(ht.TElemOf(constants.CV_ALL_ECODES_STRINGS)),
142
                  "List of error codes that should be treated as warnings")
143

    
144
#: OP_ID conversion regular expression
145
_OPID_RE = re.compile("([a-z])([A-Z])")
146

    
147
#: Utility function for L{OpClusterSetParams}
148
_TestClusterOsList = ht.TOr(ht.TNone,
149
  ht.TListOf(ht.TAnd(ht.TList, ht.TIsLength(2),
150
    ht.TMap(ht.WithDesc("GetFirstItem")(compat.fst),
151
            ht.TElemOf(constants.DDMS_VALUES)))))
152

    
153

    
154
# TODO: Generate check from constants.INIC_PARAMS_TYPES
155
#: Utility function for testing NIC definitions
156
_TestNicDef = ht.TDictOf(ht.TElemOf(constants.INIC_PARAMS),
157
                         ht.TOr(ht.TNone, ht.TNonEmptyString))
158

    
159
_TSetParamsResultItemItems = [
160
  ht.Comment("name of changed parameter")(ht.TNonEmptyString),
161
  ht.Comment("new value")(ht.TAny),
162
  ]
163

    
164
_TSetParamsResult = \
165
  ht.TListOf(ht.TAnd(ht.TIsLength(len(_TSetParamsResultItemItems)),
166
                     ht.TItems(_TSetParamsResultItemItems)))
167

    
168
_SUMMARY_PREFIX = {
169
  "CLUSTER_": "C_",
170
  "GROUP_": "G_",
171
  "NODE_": "N_",
172
  "INSTANCE_": "I_",
173
  }
174

    
175
#: Attribute name for dependencies
176
DEPEND_ATTR = "depends"
177

    
178
#: Attribute name for comment
179
COMMENT_ATTR = "comment"
180

    
181

    
182
def _NameToId(name):
183
  """Convert an opcode class name to an OP_ID.
184

185
  @type name: string
186
  @param name: the class name, as OpXxxYyy
187
  @rtype: string
188
  @return: the name in the OP_XXXX_YYYY format
189

190
  """
191
  if not name.startswith("Op"):
192
    return None
193
  # Note: (?<=[a-z])(?=[A-Z]) would be ideal, since it wouldn't
194
  # consume any input, and hence we would just have all the elements
195
  # in the list, one by one; but it seems that split doesn't work on
196
  # non-consuming input, hence we have to process the input string a
197
  # bit
198
  name = _OPID_RE.sub(r"\1,\2", name)
199
  elems = name.split(",")
200
  return "_".join(n.upper() for n in elems)
201

    
202

    
203
def RequireFileStorage():
204
  """Checks that file storage is enabled.
205

206
  While it doesn't really fit into this module, L{utils} was deemed too large
207
  of a dependency to be imported for just one or two functions.
208

209
  @raise errors.OpPrereqError: when file storage is disabled
210

211
  """
212
  if not constants.ENABLE_FILE_STORAGE:
213
    raise errors.OpPrereqError("File storage disabled at configure time",
214
                               errors.ECODE_INVAL)
215

    
216

    
217
def RequireSharedFileStorage():
218
  """Checks that shared file storage is enabled.
219

220
  While it doesn't really fit into this module, L{utils} was deemed too large
221
  of a dependency to be imported for just one or two functions.
222

223
  @raise errors.OpPrereqError: when shared file storage is disabled
224

225
  """
226
  if not constants.ENABLE_SHARED_FILE_STORAGE:
227
    raise errors.OpPrereqError("Shared file storage disabled at"
228
                               " configure time", errors.ECODE_INVAL)
229

    
230

    
231
@ht.WithDesc("CheckFileStorage")
232
def _CheckFileStorage(value):
233
  """Ensures file storage is enabled if used.
234

235
  """
236
  if value == constants.DT_FILE:
237
    RequireFileStorage()
238
  elif value == constants.DT_SHARED_FILE:
239
    RequireSharedFileStorage()
240
  return True
241

    
242

    
243
def _BuildDiskTemplateCheck(accept_none):
244
  """Builds check for disk template.
245

246
  @type accept_none: bool
247
  @param accept_none: whether to accept None as a correct value
248
  @rtype: callable
249

250
  """
251
  template_check = ht.TElemOf(constants.DISK_TEMPLATES)
252

    
253
  if accept_none:
254
    template_check = ht.TOr(template_check, ht.TNone)
255

    
256
  return ht.TAnd(template_check, _CheckFileStorage)
257

    
258

    
259
def _CheckStorageType(storage_type):
260
  """Ensure a given storage type is valid.
261

262
  """
263
  if storage_type not in constants.VALID_STORAGE_TYPES:
264
    raise errors.OpPrereqError("Unknown storage type: %s" % storage_type,
265
                               errors.ECODE_INVAL)
266
  if storage_type == constants.ST_FILE:
267
    RequireFileStorage()
268
  return True
269

    
270

    
271
#: Storage type parameter
272
_PStorageType = ("storage_type", ht.NoDefault, _CheckStorageType,
273
                 "Storage type")
274

    
275

    
276
class _AutoOpParamSlots(type):
277
  """Meta class for opcode definitions.
278

279
  """
280
  def __new__(mcs, name, bases, attrs):
281
    """Called when a class should be created.
282

283
    @param mcs: The meta class
284
    @param name: Name of created class
285
    @param bases: Base classes
286
    @type attrs: dict
287
    @param attrs: Class attributes
288

289
    """
290
    assert "__slots__" not in attrs, \
291
      "Class '%s' defines __slots__ when it should use OP_PARAMS" % name
292
    assert "OP_ID" not in attrs, "Class '%s' defining OP_ID" % name
293

    
294
    attrs["OP_ID"] = _NameToId(name)
295

    
296
    # Always set OP_PARAMS to avoid duplicates in BaseOpCode.GetAllParams
297
    params = attrs.setdefault("OP_PARAMS", [])
298

    
299
    # Use parameter names as slots
300
    slots = [pname for (pname, _, _, _) in params]
301

    
302
    assert "OP_DSC_FIELD" not in attrs or attrs["OP_DSC_FIELD"] in slots, \
303
      "Class '%s' uses unknown field in OP_DSC_FIELD" % name
304

    
305
    attrs["__slots__"] = slots
306

    
307
    return type.__new__(mcs, name, bases, attrs)
308

    
309

    
310
class BaseOpCode(object):
311
  """A simple serializable object.
312

313
  This object serves as a parent class for OpCode without any custom
314
  field handling.
315

316
  """
317
  # pylint: disable=E1101
318
  # as OP_ID is dynamically defined
319
  __metaclass__ = _AutoOpParamSlots
320

    
321
  def __init__(self, **kwargs):
322
    """Constructor for BaseOpCode.
323

324
    The constructor takes only keyword arguments and will set
325
    attributes on this object based on the passed arguments. As such,
326
    it means that you should not pass arguments which are not in the
327
    __slots__ attribute for this class.
328

329
    """
330
    slots = self._all_slots()
331
    for key in kwargs:
332
      if key not in slots:
333
        raise TypeError("Object %s doesn't support the parameter '%s'" %
334
                        (self.__class__.__name__, key))
335
      setattr(self, key, kwargs[key])
336

    
337
  def __getstate__(self):
338
    """Generic serializer.
339

340
    This method just returns the contents of the instance as a
341
    dictionary.
342

343
    @rtype:  C{dict}
344
    @return: the instance attributes and their values
345

346
    """
347
    state = {}
348
    for name in self._all_slots():
349
      if hasattr(self, name):
350
        state[name] = getattr(self, name)
351
    return state
352

    
353
  def __setstate__(self, state):
354
    """Generic unserializer.
355

356
    This method just restores from the serialized state the attributes
357
    of the current instance.
358

359
    @param state: the serialized opcode data
360
    @type state:  C{dict}
361

362
    """
363
    if not isinstance(state, dict):
364
      raise ValueError("Invalid data to __setstate__: expected dict, got %s" %
365
                       type(state))
366

    
367
    for name in self._all_slots():
368
      if name not in state and hasattr(self, name):
369
        delattr(self, name)
370

    
371
    for name in state:
372
      setattr(self, name, state[name])
373

    
374
  @classmethod
375
  def _all_slots(cls):
376
    """Compute the list of all declared slots for a class.
377

378
    """
379
    slots = []
380
    for parent in cls.__mro__:
381
      slots.extend(getattr(parent, "__slots__", []))
382
    return slots
383

    
384
  @classmethod
385
  def GetAllParams(cls):
386
    """Compute list of all parameters for an opcode.
387

388
    """
389
    slots = []
390
    for parent in cls.__mro__:
391
      slots.extend(getattr(parent, "OP_PARAMS", []))
392
    return slots
393

    
394
  def Validate(self, set_defaults):
395
    """Validate opcode parameters, optionally setting default values.
396

397
    @type set_defaults: bool
398
    @param set_defaults: Whether to set default values
399
    @raise errors.OpPrereqError: When a parameter value doesn't match
400
                                 requirements
401

402
    """
403
    for (attr_name, default, test, _) in self.GetAllParams():
404
      assert test == ht.NoType or callable(test)
405

    
406
      if not hasattr(self, attr_name):
407
        if default == ht.NoDefault:
408
          raise errors.OpPrereqError("Required parameter '%s.%s' missing" %
409
                                     (self.OP_ID, attr_name),
410
                                     errors.ECODE_INVAL)
411
        elif set_defaults:
412
          if callable(default):
413
            dval = default()
414
          else:
415
            dval = default
416
          setattr(self, attr_name, dval)
417

    
418
      if test == ht.NoType:
419
        # no tests here
420
        continue
421

    
422
      if set_defaults or hasattr(self, attr_name):
423
        attr_val = getattr(self, attr_name)
424
        if not test(attr_val):
425
          logging.error("OpCode %s, parameter %s, has invalid type %s/value %s",
426
                        self.OP_ID, attr_name, type(attr_val), attr_val)
427
          raise errors.OpPrereqError("Parameter '%s.%s' fails validation" %
428
                                     (self.OP_ID, attr_name),
429
                                     errors.ECODE_INVAL)
430

    
431

    
432
def _BuildJobDepCheck(relative):
433
  """Builds check for job dependencies (L{DEPEND_ATTR}).
434

435
  @type relative: bool
436
  @param relative: Whether to accept relative job IDs (negative)
437
  @rtype: callable
438

439
  """
440
  if relative:
441
    job_id = ht.TOr(ht.TJobId, ht.TRelativeJobId)
442
  else:
443
    job_id = ht.TJobId
444

    
445
  job_dep = \
446
    ht.TAnd(ht.TIsLength(2),
447
            ht.TItems([job_id,
448
                       ht.TListOf(ht.TElemOf(constants.JOBS_FINALIZED))]))
449

    
450
  return ht.TOr(ht.TNone, ht.TListOf(job_dep))
451

    
452

    
453
TNoRelativeJobDependencies = _BuildJobDepCheck(False)
454

    
455
#: List of submission status and job ID as returned by C{SubmitManyJobs}
456
_TJobIdListItem = \
457
  ht.TAnd(ht.TIsLength(2),
458
          ht.TItems([ht.Comment("success")(ht.TBool),
459
                     ht.Comment("Job ID if successful, error message"
460
                                " otherwise")(ht.TOr(ht.TString,
461
                                                     ht.TJobId))]))
462
TJobIdList = ht.TListOf(_TJobIdListItem)
463

    
464
#: Result containing only list of submitted jobs
465
TJobIdListOnly = ht.TStrictDict(True, True, {
466
  constants.JOB_IDS_KEY: ht.Comment("List of submitted jobs")(TJobIdList),
467
  })
468

    
469

    
470
class OpCode(BaseOpCode):
471
  """Abstract OpCode.
472

473
  This is the root of the actual OpCode hierarchy. All clases derived
474
  from this class should override OP_ID.
475

476
  @cvar OP_ID: The ID of this opcode. This should be unique amongst all
477
               children of this class.
478
  @cvar OP_DSC_FIELD: The name of a field whose value will be included in the
479
                      string returned by Summary(); see the docstring of that
480
                      method for details).
481
  @cvar OP_PARAMS: List of opcode attributes, the default values they should
482
                   get if not already defined, and types they must match.
483
  @cvar OP_RESULT: Callable to verify opcode result
484
  @cvar WITH_LU: Boolean that specifies whether this should be included in
485
      mcpu's dispatch table
486
  @ivar dry_run: Whether the LU should be run in dry-run mode, i.e. just
487
                 the check steps
488
  @ivar priority: Opcode priority for queue
489

490
  """
491
  # pylint: disable=E1101
492
  # as OP_ID is dynamically defined
493
  WITH_LU = True
494
  OP_PARAMS = [
495
    ("dry_run", None, ht.TMaybeBool, "Run checks only, don't execute"),
496
    ("debug_level", None, ht.TOr(ht.TNone, ht.TPositiveInt), "Debug level"),
497
    ("priority", constants.OP_PRIO_DEFAULT,
498
     ht.TElemOf(constants.OP_PRIO_SUBMIT_VALID), "Opcode priority"),
499
    (DEPEND_ATTR, None, _BuildJobDepCheck(True),
500
     "Job dependencies; if used through ``SubmitManyJobs`` relative (negative)"
501
     " job IDs can be used"),
502
    (COMMENT_ATTR, None, ht.TMaybeString,
503
     "Comment describing the purpose of the opcode"),
504
    ]
505
  OP_RESULT = None
506

    
507
  def __getstate__(self):
508
    """Specialized getstate for opcodes.
509

510
    This method adds to the state dictionary the OP_ID of the class,
511
    so that on unload we can identify the correct class for
512
    instantiating the opcode.
513

514
    @rtype:   C{dict}
515
    @return:  the state as a dictionary
516

517
    """
518
    data = BaseOpCode.__getstate__(self)
519
    data["OP_ID"] = self.OP_ID
520
    return data
521

    
522
  @classmethod
523
  def LoadOpCode(cls, data):
524
    """Generic load opcode method.
525

526
    The method identifies the correct opcode class from the dict-form
527
    by looking for a OP_ID key, if this is not found, or its value is
528
    not available in this module as a child of this class, we fail.
529

530
    @type data:  C{dict}
531
    @param data: the serialized opcode
532

533
    """
534
    if not isinstance(data, dict):
535
      raise ValueError("Invalid data to LoadOpCode (%s)" % type(data))
536
    if "OP_ID" not in data:
537
      raise ValueError("Invalid data to LoadOpcode, missing OP_ID")
538
    op_id = data["OP_ID"]
539
    op_class = None
540
    if op_id in OP_MAPPING:
541
      op_class = OP_MAPPING[op_id]
542
    else:
543
      raise ValueError("Invalid data to LoadOpCode: OP_ID %s unsupported" %
544
                       op_id)
545
    op = op_class()
546
    new_data = data.copy()
547
    del new_data["OP_ID"]
548
    op.__setstate__(new_data)
549
    return op
550

    
551
  def Summary(self):
552
    """Generates a summary description of this opcode.
553

554
    The summary is the value of the OP_ID attribute (without the "OP_"
555
    prefix), plus the value of the OP_DSC_FIELD attribute, if one was
556
    defined; this field should allow to easily identify the operation
557
    (for an instance creation job, e.g., it would be the instance
558
    name).
559

560
    """
561
    assert self.OP_ID is not None and len(self.OP_ID) > 3
562
    # all OP_ID start with OP_, we remove that
563
    txt = self.OP_ID[3:]
564
    field_name = getattr(self, "OP_DSC_FIELD", None)
565
    if field_name:
566
      field_value = getattr(self, field_name, None)
567
      if isinstance(field_value, (list, tuple)):
568
        field_value = ",".join(str(i) for i in field_value)
569
      txt = "%s(%s)" % (txt, field_value)
570
    return txt
571

    
572
  def TinySummary(self):
573
    """Generates a compact summary description of the opcode.
574

575
    """
576
    assert self.OP_ID.startswith("OP_")
577

    
578
    text = self.OP_ID[3:]
579

    
580
    for (prefix, supplement) in _SUMMARY_PREFIX.items():
581
      if text.startswith(prefix):
582
        return supplement + text[len(prefix):]
583

    
584
    return text
585

    
586

    
587
# cluster opcodes
588

    
589
class OpClusterPostInit(OpCode):
590
  """Post cluster initialization.
591

592
  This opcode does not touch the cluster at all. Its purpose is to run hooks
593
  after the cluster has been initialized.
594

595
  """
596

    
597

    
598
class OpClusterDestroy(OpCode):
599
  """Destroy the cluster.
600

601
  This opcode has no other parameters. All the state is irreversibly
602
  lost after the execution of this opcode.
603

604
  """
605

    
606

    
607
class OpClusterQuery(OpCode):
608
  """Query cluster information."""
609

    
610

    
611
class OpClusterVerify(OpCode):
612
  """Submits all jobs necessary to verify the cluster.
613

614
  """
615
  OP_PARAMS = [
616
    _PDebugSimulateErrors,
617
    _PErrorCodes,
618
    _PSkipChecks,
619
    _PIgnoreErrors,
620
    _PVerbose,
621
    ("group_name", None, ht.TMaybeString, "Group to verify")
622
    ]
623
  OP_RESULT = TJobIdListOnly
624

    
625

    
626
class OpClusterVerifyConfig(OpCode):
627
  """Verify the cluster config.
628

629
  """
630
  OP_PARAMS = [
631
    _PDebugSimulateErrors,
632
    _PErrorCodes,
633
    _PIgnoreErrors,
634
    _PVerbose,
635
    ]
636
  OP_RESULT = ht.TBool
637

    
638

    
639
class OpClusterVerifyGroup(OpCode):
640
  """Run verify on a node group from the cluster.
641

642
  @type skip_checks: C{list}
643
  @ivar skip_checks: steps to be skipped from the verify process; this
644
                     needs to be a subset of
645
                     L{constants.VERIFY_OPTIONAL_CHECKS}; currently
646
                     only L{constants.VERIFY_NPLUSONE_MEM} can be passed
647

648
  """
649
  OP_DSC_FIELD = "group_name"
650
  OP_PARAMS = [
651
    _PGroupName,
652
    _PDebugSimulateErrors,
653
    _PErrorCodes,
654
    _PSkipChecks,
655
    _PIgnoreErrors,
656
    _PVerbose,
657
    ]
658
  OP_RESULT = ht.TBool
659

    
660

    
661
class OpClusterVerifyDisks(OpCode):
662
  """Verify the cluster disks.
663

664
  """
665
  OP_RESULT = TJobIdListOnly
666

    
667

    
668
class OpGroupVerifyDisks(OpCode):
669
  """Verifies the status of all disks in a node group.
670

671
  Result: a tuple of three elements:
672
    - dict of node names with issues (values: error msg)
673
    - list of instances with degraded disks (that should be activated)
674
    - dict of instances with missing logical volumes (values: (node, vol)
675
      pairs with details about the missing volumes)
676

677
  In normal operation, all lists should be empty. A non-empty instance
678
  list (3rd element of the result) is still ok (errors were fixed) but
679
  non-empty node list means some node is down, and probably there are
680
  unfixable drbd errors.
681

682
  Note that only instances that are drbd-based are taken into
683
  consideration. This might need to be revisited in the future.
684

685
  """
686
  OP_DSC_FIELD = "group_name"
687
  OP_PARAMS = [
688
    _PGroupName,
689
    ]
690
  OP_RESULT = \
691
    ht.TAnd(ht.TIsLength(3),
692
            ht.TItems([ht.TDictOf(ht.TString, ht.TString),
693
                       ht.TListOf(ht.TString),
694
                       ht.TDictOf(ht.TString,
695
                                  ht.TListOf(ht.TListOf(ht.TString)))]))
696

    
697

    
698
class OpClusterRepairDiskSizes(OpCode):
699
  """Verify the disk sizes of the instances and fixes configuration
700
  mimatches.
701

702
  Parameters: optional instances list, in case we want to restrict the
703
  checks to only a subset of the instances.
704

705
  Result: a list of tuples, (instance, disk, new-size) for changed
706
  configurations.
707

708
  In normal operation, the list should be empty.
709

710
  @type instances: list
711
  @ivar instances: the list of instances to check, or empty for all instances
712

713
  """
714
  OP_PARAMS = [
715
    ("instances", ht.EmptyList, ht.TListOf(ht.TNonEmptyString), None),
716
    ]
717

    
718

    
719
class OpClusterConfigQuery(OpCode):
720
  """Query cluster configuration values."""
721
  OP_PARAMS = [
722
    _POutputFields
723
    ]
724

    
725

    
726
class OpClusterRename(OpCode):
727
  """Rename the cluster.
728

729
  @type name: C{str}
730
  @ivar name: The new name of the cluster. The name and/or the master IP
731
              address will be changed to match the new name and its IP
732
              address.
733

734
  """
735
  OP_DSC_FIELD = "name"
736
  OP_PARAMS = [
737
    ("name", ht.NoDefault, ht.TNonEmptyString, None),
738
    ]
739

    
740

    
741
class OpClusterSetParams(OpCode):
742
  """Change the parameters of the cluster.
743

744
  @type vg_name: C{str} or C{None}
745
  @ivar vg_name: The new volume group name or None to disable LVM usage.
746

747
  """
748
  OP_PARAMS = [
749
    ("vg_name", None, ht.TMaybeString, "Volume group name"),
750
    ("enabled_hypervisors", None,
751
     ht.TOr(ht.TAnd(ht.TListOf(ht.TElemOf(constants.HYPER_TYPES)), ht.TTrue),
752
            ht.TNone),
753
     "List of enabled hypervisors"),
754
    ("hvparams", None, ht.TOr(ht.TDictOf(ht.TNonEmptyString, ht.TDict),
755
                              ht.TNone),
756
     "Cluster-wide hypervisor parameter defaults, hypervisor-dependent"),
757
    ("beparams", None, ht.TOr(ht.TDict, ht.TNone),
758
     "Cluster-wide backend parameter defaults"),
759
    ("os_hvp", None, ht.TOr(ht.TDictOf(ht.TNonEmptyString, ht.TDict),
760
                            ht.TNone),
761
     "Cluster-wide per-OS hypervisor parameter defaults"),
762
    ("osparams", None, ht.TOr(ht.TDictOf(ht.TNonEmptyString, ht.TDict),
763
                              ht.TNone),
764
     "Cluster-wide OS parameter defaults"),
765
    ("candidate_pool_size", None, ht.TOr(ht.TStrictPositiveInt, ht.TNone),
766
     "Master candidate pool size"),
767
    ("uid_pool", None, ht.NoType,
768
     "Set UID pool, must be list of lists describing UID ranges (two items,"
769
     " start and end inclusive)"),
770
    ("add_uids", None, ht.NoType,
771
     "Extend UID pool, must be list of lists describing UID ranges (two"
772
     " items, start and end inclusive) to be added"),
773
    ("remove_uids", None, ht.NoType,
774
     "Shrink UID pool, must be list of lists describing UID ranges (two"
775
     " items, start and end inclusive) to be removed"),
776
    ("maintain_node_health", None, ht.TMaybeBool,
777
     "Whether to automatically maintain node health"),
778
    ("prealloc_wipe_disks", None, ht.TMaybeBool,
779
     "Whether to wipe disks before allocating them to instances"),
780
    ("nicparams", None, ht.TMaybeDict, "Cluster-wide NIC parameter defaults"),
781
    ("ndparams", None, ht.TMaybeDict, "Cluster-wide node parameter defaults"),
782
    ("drbd_helper", None, ht.TOr(ht.TString, ht.TNone), "DRBD helper program"),
783
    ("default_iallocator", None, ht.TOr(ht.TString, ht.TNone),
784
     "Default iallocator for cluster"),
785
    ("master_netdev", None, ht.TOr(ht.TString, ht.TNone),
786
     "Master network device"),
787
    ("master_netmask", None, ht.TOr(ht.TInt, ht.TNone),
788
     "Netmask of the master IP"),
789
    ("reserved_lvs", None, ht.TOr(ht.TListOf(ht.TNonEmptyString), ht.TNone),
790
     "List of reserved LVs"),
791
    ("hidden_os", None, _TestClusterOsList,
792
     "Modify list of hidden operating systems. Each modification must have"
793
     " two items, the operation and the OS name. The operation can be"
794
     " ``%s`` or ``%s``." % (constants.DDM_ADD, constants.DDM_REMOVE)),
795
    ("blacklisted_os", None, _TestClusterOsList,
796
     "Modify list of blacklisted operating systems. Each modification must have"
797
     " two items, the operation and the OS name. The operation can be"
798
     " ``%s`` or ``%s``." % (constants.DDM_ADD, constants.DDM_REMOVE)),
799
    ("use_external_mip_script", None, ht.TMaybeBool,
800
     "Whether to use an external master IP address setup script"),
801
    ]
802

    
803

    
804
class OpClusterRedistConf(OpCode):
805
  """Force a full push of the cluster configuration.
806

807
  """
808

    
809

    
810
class OpClusterActivateMasterIp(OpCode):
811
  """Activate the master IP on the master node.
812

813
  """
814

    
815

    
816
class OpClusterDeactivateMasterIp(OpCode):
817
  """Deactivate the master IP on the master node.
818

819
  """
820

    
821

    
822
class OpQuery(OpCode):
823
  """Query for resources/items.
824

825
  @ivar what: Resources to query for, must be one of L{constants.QR_VIA_OP}
826
  @ivar fields: List of fields to retrieve
827
  @ivar qfilter: Query filter
828

829
  """
830
  OP_DSC_FIELD = "what"
831
  OP_PARAMS = [
832
    _PQueryWhat,
833
    _PUseLocking,
834
    ("fields", ht.NoDefault, ht.TListOf(ht.TNonEmptyString),
835
     "Requested fields"),
836
    ("qfilter", None, ht.TOr(ht.TNone, ht.TListOf),
837
     "Query filter"),
838
    ]
839

    
840

    
841
class OpQueryFields(OpCode):
842
  """Query for available resource/item fields.
843

844
  @ivar what: Resources to query for, must be one of L{constants.QR_VIA_OP}
845
  @ivar fields: List of fields to retrieve
846

847
  """
848
  OP_DSC_FIELD = "what"
849
  OP_PARAMS = [
850
    _PQueryWhat,
851
    ("fields", None, ht.TOr(ht.TNone, ht.TListOf(ht.TNonEmptyString)),
852
     "Requested fields; if not given, all are returned"),
853
    ]
854

    
855

    
856
class OpOobCommand(OpCode):
857
  """Interact with OOB."""
858
  OP_PARAMS = [
859
    ("node_names", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
860
     "List of nodes to run the OOB command against"),
861
    ("command", None, ht.TElemOf(constants.OOB_COMMANDS),
862
     "OOB command to be run"),
863
    ("timeout", constants.OOB_TIMEOUT, ht.TInt,
864
     "Timeout before the OOB helper will be terminated"),
865
    ("ignore_status", False, ht.TBool,
866
     "Ignores the node offline status for power off"),
867
    ("power_delay", constants.OOB_POWER_DELAY, ht.TPositiveFloat,
868
     "Time in seconds to wait between powering on nodes"),
869
    ]
870

    
871

    
872
# node opcodes
873

    
874
class OpNodeRemove(OpCode):
875
  """Remove a node.
876

877
  @type node_name: C{str}
878
  @ivar node_name: The name of the node to remove. If the node still has
879
                   instances on it, the operation will fail.
880

881
  """
882
  OP_DSC_FIELD = "node_name"
883
  OP_PARAMS = [
884
    _PNodeName,
885
    ]
886

    
887

    
888
class OpNodeAdd(OpCode):
889
  """Add a node to the cluster.
890

891
  @type node_name: C{str}
892
  @ivar node_name: The name of the node to add. This can be a short name,
893
                   but it will be expanded to the FQDN.
894
  @type primary_ip: IP address
895
  @ivar primary_ip: The primary IP of the node. This will be ignored when the
896
                    opcode is submitted, but will be filled during the node
897
                    add (so it will be visible in the job query).
898
  @type secondary_ip: IP address
899
  @ivar secondary_ip: The secondary IP of the node. This needs to be passed
900
                      if the cluster has been initialized in 'dual-network'
901
                      mode, otherwise it must not be given.
902
  @type readd: C{bool}
903
  @ivar readd: Whether to re-add an existing node to the cluster. If
904
               this is not passed, then the operation will abort if the node
905
               name is already in the cluster; use this parameter to 'repair'
906
               a node that had its configuration broken, or was reinstalled
907
               without removal from the cluster.
908
  @type group: C{str}
909
  @ivar group: The node group to which this node will belong.
910
  @type vm_capable: C{bool}
911
  @ivar vm_capable: The vm_capable node attribute
912
  @type master_capable: C{bool}
913
  @ivar master_capable: The master_capable node attribute
914

915
  """
916
  OP_DSC_FIELD = "node_name"
917
  OP_PARAMS = [
918
    _PNodeName,
919
    ("primary_ip", None, ht.NoType, "Primary IP address"),
920
    ("secondary_ip", None, ht.TMaybeString, "Secondary IP address"),
921
    ("readd", False, ht.TBool, "Whether node is re-added to cluster"),
922
    ("group", None, ht.TMaybeString, "Initial node group"),
923
    ("master_capable", None, ht.TMaybeBool,
924
     "Whether node can become master or master candidate"),
925
    ("vm_capable", None, ht.TMaybeBool,
926
     "Whether node can host instances"),
927
    ("ndparams", None, ht.TMaybeDict, "Node parameters"),
928
    ]
929

    
930

    
931
class OpNodeQuery(OpCode):
932
  """Compute the list of nodes."""
933
  OP_PARAMS = [
934
    _POutputFields,
935
    _PUseLocking,
936
    ("names", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
937
     "Empty list to query all nodes, node names otherwise"),
938
    ]
939

    
940

    
941
class OpNodeQueryvols(OpCode):
942
  """Get list of volumes on node."""
943
  OP_PARAMS = [
944
    _POutputFields,
945
    ("nodes", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
946
     "Empty list to query all nodes, node names otherwise"),
947
    ]
948

    
949

    
950
class OpNodeQueryStorage(OpCode):
951
  """Get information on storage for node(s)."""
952
  OP_PARAMS = [
953
    _POutputFields,
954
    _PStorageType,
955
    ("nodes", ht.EmptyList, ht.TListOf(ht.TNonEmptyString), "List of nodes"),
956
    ("name", None, ht.TMaybeString, "Storage name"),
957
    ]
958

    
959

    
960
class OpNodeModifyStorage(OpCode):
961
  """Modifies the properies of a storage unit"""
962
  OP_PARAMS = [
963
    _PNodeName,
964
    _PStorageType,
965
    _PStorageName,
966
    ("changes", ht.NoDefault, ht.TDict, "Requested changes"),
967
    ]
968

    
969

    
970
class OpRepairNodeStorage(OpCode):
971
  """Repairs the volume group on a node."""
972
  OP_DSC_FIELD = "node_name"
973
  OP_PARAMS = [
974
    _PNodeName,
975
    _PStorageType,
976
    _PStorageName,
977
    _PIgnoreConsistency,
978
    ]
979

    
980

    
981
class OpNodeSetParams(OpCode):
982
  """Change the parameters of a node."""
983
  OP_DSC_FIELD = "node_name"
984
  OP_PARAMS = [
985
    _PNodeName,
986
    _PForce,
987
    ("master_candidate", None, ht.TMaybeBool,
988
     "Whether the node should become a master candidate"),
989
    ("offline", None, ht.TMaybeBool,
990
     "Whether the node should be marked as offline"),
991
    ("drained", None, ht.TMaybeBool,
992
     "Whether the node should be marked as drained"),
993
    ("auto_promote", False, ht.TBool,
994
     "Whether node(s) should be promoted to master candidate if necessary"),
995
    ("master_capable", None, ht.TMaybeBool,
996
     "Denote whether node can become master or master candidate"),
997
    ("vm_capable", None, ht.TMaybeBool,
998
     "Denote whether node can host instances"),
999
    ("secondary_ip", None, ht.TMaybeString,
1000
     "Change node's secondary IP address"),
1001
    ("ndparams", None, ht.TMaybeDict, "Set node parameters"),
1002
    ("powered", None, ht.TMaybeBool,
1003
     "Whether the node should be marked as powered"),
1004
    ]
1005
  OP_RESULT = _TSetParamsResult
1006

    
1007

    
1008
class OpNodePowercycle(OpCode):
1009
  """Tries to powercycle a node."""
1010
  OP_DSC_FIELD = "node_name"
1011
  OP_PARAMS = [
1012
    _PNodeName,
1013
    _PForce,
1014
    ]
1015

    
1016

    
1017
class OpNodeMigrate(OpCode):
1018
  """Migrate all instances from a node."""
1019
  OP_DSC_FIELD = "node_name"
1020
  OP_PARAMS = [
1021
    _PNodeName,
1022
    _PMigrationMode,
1023
    _PMigrationLive,
1024
    _PMigrationTargetNode,
1025
    ("iallocator", None, ht.TMaybeString,
1026
     "Iallocator for deciding the target node for shared-storage instances"),
1027
    ]
1028

    
1029

    
1030
class OpNodeEvacuate(OpCode):
1031
  """Evacuate instances off a number of nodes."""
1032
  OP_DSC_FIELD = "node_name"
1033
  OP_PARAMS = [
1034
    _PEarlyRelease,
1035
    _PNodeName,
1036
    ("remote_node", None, ht.TMaybeString, "New secondary node"),
1037
    ("iallocator", None, ht.TMaybeString, "Iallocator for computing solution"),
1038
    ("mode", ht.NoDefault, ht.TElemOf(constants.IALLOCATOR_NEVAC_MODES),
1039
     "Node evacuation mode"),
1040
    ]
1041
  OP_RESULT = TJobIdListOnly
1042

    
1043

    
1044
# instance opcodes
1045

    
1046
class OpInstanceCreate(OpCode):
1047
  """Create an instance.
1048

1049
  @ivar instance_name: Instance name
1050
  @ivar mode: Instance creation mode (one of L{constants.INSTANCE_CREATE_MODES})
1051
  @ivar source_handshake: Signed handshake from source (remote import only)
1052
  @ivar source_x509_ca: Source X509 CA in PEM format (remote import only)
1053
  @ivar source_instance_name: Previous name of instance (remote import only)
1054
  @ivar source_shutdown_timeout: Shutdown timeout used for source instance
1055
    (remote import only)
1056

1057
  """
1058
  OP_DSC_FIELD = "instance_name"
1059
  OP_PARAMS = [
1060
    _PInstanceName,
1061
    _PForceVariant,
1062
    _PWaitForSync,
1063
    _PNameCheck,
1064
    ("beparams", ht.EmptyDict, ht.TDict, "Backend parameters for instance"),
1065
    ("disks", ht.NoDefault,
1066
     # TODO: Generate check from constants.IDISK_PARAMS_TYPES
1067
     ht.TListOf(ht.TDictOf(ht.TElemOf(constants.IDISK_PARAMS),
1068
                           ht.TOr(ht.TNonEmptyString, ht.TInt))),
1069
     "Disk descriptions, for example ``[{\"%s\": 100}, {\"%s\": 5}]``;"
1070
     " each disk definition must contain a ``%s`` value and"
1071
     " can contain an optional ``%s`` value denoting the disk access mode"
1072
     " (%s)" %
1073
     (constants.IDISK_SIZE, constants.IDISK_SIZE, constants.IDISK_SIZE,
1074
      constants.IDISK_MODE,
1075
      " or ".join("``%s``" % i for i in sorted(constants.DISK_ACCESS_SET)))),
1076
    ("disk_template", ht.NoDefault, _BuildDiskTemplateCheck(True),
1077
     "Disk template"),
1078
    ("file_driver", None, ht.TOr(ht.TNone, ht.TElemOf(constants.FILE_DRIVER)),
1079
     "Driver for file-backed disks"),
1080
    ("file_storage_dir", None, ht.TMaybeString,
1081
     "Directory for storing file-backed disks"),
1082
    ("hvparams", ht.EmptyDict, ht.TDict,
1083
     "Hypervisor parameters for instance, hypervisor-dependent"),
1084
    ("hypervisor", None, ht.TMaybeString, "Hypervisor"),
1085
    ("iallocator", None, ht.TMaybeString,
1086
     "Iallocator for deciding which node(s) to use"),
1087
    ("identify_defaults", False, ht.TBool,
1088
     "Reset instance parameters to default if equal"),
1089
    ("ip_check", True, ht.TBool, _PIpCheckDoc),
1090
    ("mode", ht.NoDefault, ht.TElemOf(constants.INSTANCE_CREATE_MODES),
1091
     "Instance creation mode"),
1092
    ("nics", ht.NoDefault, ht.TListOf(_TestNicDef),
1093
     "List of NIC (network interface) definitions, for example"
1094
     " ``[{}, {}, {\"%s\": \"198.51.100.4\"}]``; each NIC definition can"
1095
     " contain the optional values %s" %
1096
     (constants.INIC_IP,
1097
      ", ".join("``%s``" % i for i in sorted(constants.INIC_PARAMS)))),
1098
    ("no_install", None, ht.TMaybeBool,
1099
     "Do not install the OS (will disable automatic start)"),
1100
    ("osparams", ht.EmptyDict, ht.TDict, "OS parameters for instance"),
1101
    ("os_type", None, ht.TMaybeString, "Operating system"),
1102
    ("pnode", None, ht.TMaybeString, "Primary node"),
1103
    ("snode", None, ht.TMaybeString, "Secondary node"),
1104
    ("source_handshake", None, ht.TOr(ht.TList, ht.TNone),
1105
     "Signed handshake from source (remote import only)"),
1106
    ("source_instance_name", None, ht.TMaybeString,
1107
     "Source instance name (remote import only)"),
1108
    ("source_shutdown_timeout", constants.DEFAULT_SHUTDOWN_TIMEOUT,
1109
     ht.TPositiveInt,
1110
     "How long source instance was given to shut down (remote import only)"),
1111
    ("source_x509_ca", None, ht.TMaybeString,
1112
     "Source X509 CA in PEM format (remote import only)"),
1113
    ("src_node", None, ht.TMaybeString, "Source node for import"),
1114
    ("src_path", None, ht.TMaybeString, "Source directory for import"),
1115
    ("start", True, ht.TBool, "Whether to start instance after creation"),
1116
    ("tags", ht.EmptyList, ht.TListOf(ht.TNonEmptyString), "Instance tags"),
1117
    ]
1118
  OP_RESULT = ht.Comment("instance nodes")(ht.TListOf(ht.TNonEmptyString))
1119

    
1120

    
1121
class OpInstanceReinstall(OpCode):
1122
  """Reinstall an instance's OS."""
1123
  OP_DSC_FIELD = "instance_name"
1124
  OP_PARAMS = [
1125
    _PInstanceName,
1126
    _PForceVariant,
1127
    ("os_type", None, ht.TMaybeString, "Instance operating system"),
1128
    ("osparams", None, ht.TMaybeDict, "Temporary OS parameters"),
1129
    ]
1130

    
1131

    
1132
class OpInstanceRemove(OpCode):
1133
  """Remove an instance."""
1134
  OP_DSC_FIELD = "instance_name"
1135
  OP_PARAMS = [
1136
    _PInstanceName,
1137
    _PShutdownTimeout,
1138
    ("ignore_failures", False, ht.TBool,
1139
     "Whether to ignore failures during removal"),
1140
    ]
1141

    
1142

    
1143
class OpInstanceRename(OpCode):
1144
  """Rename an instance."""
1145
  OP_PARAMS = [
1146
    _PInstanceName,
1147
    _PNameCheck,
1148
    ("new_name", ht.NoDefault, ht.TNonEmptyString, "New instance name"),
1149
    ("ip_check", False, ht.TBool, _PIpCheckDoc),
1150
    ]
1151
  OP_RESULT = ht.Comment("New instance name")(ht.TNonEmptyString)
1152

    
1153

    
1154
class OpInstanceStartup(OpCode):
1155
  """Startup an instance."""
1156
  OP_DSC_FIELD = "instance_name"
1157
  OP_PARAMS = [
1158
    _PInstanceName,
1159
    _PForce,
1160
    _PIgnoreOfflineNodes,
1161
    ("hvparams", ht.EmptyDict, ht.TDict,
1162
     "Temporary hypervisor parameters, hypervisor-dependent"),
1163
    ("beparams", ht.EmptyDict, ht.TDict, "Temporary backend parameters"),
1164
    _PNoRemember,
1165
    _PStartupPaused,
1166
    ]
1167

    
1168

    
1169
class OpInstanceShutdown(OpCode):
1170
  """Shutdown an instance."""
1171
  OP_DSC_FIELD = "instance_name"
1172
  OP_PARAMS = [
1173
    _PInstanceName,
1174
    _PIgnoreOfflineNodes,
1175
    ("timeout", constants.DEFAULT_SHUTDOWN_TIMEOUT, ht.TPositiveInt,
1176
     "How long to wait for instance to shut down"),
1177
    _PNoRemember,
1178
    ]
1179

    
1180

    
1181
class OpInstanceReboot(OpCode):
1182
  """Reboot an instance."""
1183
  OP_DSC_FIELD = "instance_name"
1184
  OP_PARAMS = [
1185
    _PInstanceName,
1186
    _PShutdownTimeout,
1187
    ("ignore_secondaries", False, ht.TBool,
1188
     "Whether to start the instance even if secondary disks are failing"),
1189
    ("reboot_type", ht.NoDefault, ht.TElemOf(constants.REBOOT_TYPES),
1190
     "How to reboot instance"),
1191
    ]
1192

    
1193

    
1194
class OpInstanceReplaceDisks(OpCode):
1195
  """Replace the disks of an instance."""
1196
  OP_DSC_FIELD = "instance_name"
1197
  OP_PARAMS = [
1198
    _PInstanceName,
1199
    _PEarlyRelease,
1200
    ("mode", ht.NoDefault, ht.TElemOf(constants.REPLACE_MODES),
1201
     "Replacement mode"),
1202
    ("disks", ht.EmptyList, ht.TListOf(ht.TPositiveInt),
1203
     "Disk indexes"),
1204
    ("remote_node", None, ht.TMaybeString, "New secondary node"),
1205
    ("iallocator", None, ht.TMaybeString,
1206
     "Iallocator for deciding new secondary node"),
1207
    ]
1208

    
1209

    
1210
class OpInstanceFailover(OpCode):
1211
  """Failover an instance."""
1212
  OP_DSC_FIELD = "instance_name"
1213
  OP_PARAMS = [
1214
    _PInstanceName,
1215
    _PShutdownTimeout,
1216
    _PIgnoreConsistency,
1217
    _PMigrationTargetNode,
1218
    ("iallocator", None, ht.TMaybeString,
1219
     "Iallocator for deciding the target node for shared-storage instances"),
1220
    ]
1221

    
1222

    
1223
class OpInstanceMigrate(OpCode):
1224
  """Migrate an instance.
1225

1226
  This migrates (without shutting down an instance) to its secondary
1227
  node.
1228

1229
  @ivar instance_name: the name of the instance
1230
  @ivar mode: the migration mode (live, non-live or None for auto)
1231

1232
  """
1233
  OP_DSC_FIELD = "instance_name"
1234
  OP_PARAMS = [
1235
    _PInstanceName,
1236
    _PMigrationMode,
1237
    _PMigrationLive,
1238
    _PMigrationTargetNode,
1239
    ("cleanup", False, ht.TBool,
1240
     "Whether a previously failed migration should be cleaned up"),
1241
    ("iallocator", None, ht.TMaybeString,
1242
     "Iallocator for deciding the target node for shared-storage instances"),
1243
    ("allow_failover", False, ht.TBool,
1244
     "Whether we can fallback to failover if migration is not possible"),
1245
    ]
1246

    
1247

    
1248
class OpInstanceMove(OpCode):
1249
  """Move an instance.
1250

1251
  This move (with shutting down an instance and data copying) to an
1252
  arbitrary node.
1253

1254
  @ivar instance_name: the name of the instance
1255
  @ivar target_node: the destination node
1256

1257
  """
1258
  OP_DSC_FIELD = "instance_name"
1259
  OP_PARAMS = [
1260
    _PInstanceName,
1261
    _PShutdownTimeout,
1262
    ("target_node", ht.NoDefault, ht.TNonEmptyString, "Target node"),
1263
    _PIgnoreConsistency,
1264
    ]
1265

    
1266

    
1267
class OpInstanceConsole(OpCode):
1268
  """Connect to an instance's console."""
1269
  OP_DSC_FIELD = "instance_name"
1270
  OP_PARAMS = [
1271
    _PInstanceName
1272
    ]
1273

    
1274

    
1275
class OpInstanceActivateDisks(OpCode):
1276
  """Activate an instance's disks."""
1277
  OP_DSC_FIELD = "instance_name"
1278
  OP_PARAMS = [
1279
    _PInstanceName,
1280
    ("ignore_size", False, ht.TBool, "Whether to ignore recorded size"),
1281
    ]
1282

    
1283

    
1284
class OpInstanceDeactivateDisks(OpCode):
1285
  """Deactivate an instance's disks."""
1286
  OP_DSC_FIELD = "instance_name"
1287
  OP_PARAMS = [
1288
    _PInstanceName,
1289
    _PForce,
1290
    ]
1291

    
1292

    
1293
class OpInstanceRecreateDisks(OpCode):
1294
  """Recreate an instance's disks."""
1295
  OP_DSC_FIELD = "instance_name"
1296
  OP_PARAMS = [
1297
    _PInstanceName,
1298
    ("disks", ht.EmptyList, ht.TListOf(ht.TPositiveInt),
1299
     "List of disk indexes"),
1300
    ("nodes", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
1301
     "New instance nodes, if relocation is desired"),
1302
    ]
1303

    
1304

    
1305
class OpInstanceQuery(OpCode):
1306
  """Compute the list of instances."""
1307
  OP_PARAMS = [
1308
    _POutputFields,
1309
    _PUseLocking,
1310
    ("names", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
1311
     "Empty list to query all instances, instance names otherwise"),
1312
    ]
1313

    
1314

    
1315
class OpInstanceQueryData(OpCode):
1316
  """Compute the run-time status of instances."""
1317
  OP_PARAMS = [
1318
    _PUseLocking,
1319
    ("instances", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
1320
     "Instance names"),
1321
    ("static", False, ht.TBool,
1322
     "Whether to only return configuration data without querying"
1323
     " nodes"),
1324
    ]
1325

    
1326

    
1327
class OpInstanceSetParams(OpCode):
1328
  """Change the parameters of an instance."""
1329
  OP_DSC_FIELD = "instance_name"
1330
  OP_PARAMS = [
1331
    _PInstanceName,
1332
    _PForce,
1333
    _PForceVariant,
1334
    # TODO: Use _TestNicDef
1335
    ("nics", ht.EmptyList, ht.TList,
1336
     "List of NIC changes. Each item is of the form ``(op, settings)``."
1337
     " ``op`` can be ``%s`` to add a new NIC with the specified settings,"
1338
     " ``%s`` to remove the last NIC or a number to modify the settings"
1339
     " of the NIC with that index." %
1340
     (constants.DDM_ADD, constants.DDM_REMOVE)),
1341
    ("disks", ht.EmptyList, ht.TList, "List of disk changes. See ``nics``."),
1342
    ("beparams", ht.EmptyDict, ht.TDict, "Per-instance backend parameters"),
1343
    ("hvparams", ht.EmptyDict, ht.TDict,
1344
     "Per-instance hypervisor parameters, hypervisor-dependent"),
1345
    ("disk_template", None, ht.TOr(ht.TNone, _BuildDiskTemplateCheck(False)),
1346
     "Disk template for instance"),
1347
    ("remote_node", None, ht.TMaybeString,
1348
     "Secondary node (used when changing disk template)"),
1349
    ("os_name", None, ht.TMaybeString,
1350
     "Change instance's OS name. Does not reinstall the instance."),
1351
    ("osparams", None, ht.TMaybeDict, "Per-instance OS parameters"),
1352
    ("wait_for_sync", True, ht.TBool,
1353
     "Whether to wait for the disk to synchronize, when changing template"),
1354
    ("offline_inst", False, ht.TBool,
1355
     "Whether to turn off the down instance completely"),
1356
    ("online_inst", False, ht.TBool,
1357
     "Whether to enable the offline instance"),
1358
    ]
1359
  OP_RESULT = _TSetParamsResult
1360

    
1361

    
1362
class OpInstanceGrowDisk(OpCode):
1363
  """Grow a disk of an instance."""
1364
  OP_DSC_FIELD = "instance_name"
1365
  OP_PARAMS = [
1366
    _PInstanceName,
1367
    _PWaitForSync,
1368
    ("disk", ht.NoDefault, ht.TInt, "Disk index"),
1369
    ("amount", ht.NoDefault, ht.TInt,
1370
     "Amount of disk space to add (megabytes)"),
1371
    ]
1372

    
1373

    
1374
class OpInstanceChangeGroup(OpCode):
1375
  """Moves an instance to another node group."""
1376
  OP_DSC_FIELD = "instance_name"
1377
  OP_PARAMS = [
1378
    _PInstanceName,
1379
    _PEarlyRelease,
1380
    ("iallocator", None, ht.TMaybeString, "Iallocator for computing solution"),
1381
    ("target_groups", None, ht.TOr(ht.TNone, ht.TListOf(ht.TNonEmptyString)),
1382
     "Destination group names or UUIDs (defaults to \"all but current group\""),
1383
    ]
1384
  OP_RESULT = TJobIdListOnly
1385

    
1386

    
1387
# Node group opcodes
1388

    
1389
class OpGroupAdd(OpCode):
1390
  """Add a node group to the cluster."""
1391
  OP_DSC_FIELD = "group_name"
1392
  OP_PARAMS = [
1393
    _PGroupName,
1394
    _PNodeGroupAllocPolicy,
1395
    _PGroupNodeParams,
1396
    ]
1397

    
1398

    
1399
class OpGroupAssignNodes(OpCode):
1400
  """Assign nodes to a node group."""
1401
  OP_DSC_FIELD = "group_name"
1402
  OP_PARAMS = [
1403
    _PGroupName,
1404
    _PForce,
1405
    ("nodes", ht.NoDefault, ht.TListOf(ht.TNonEmptyString),
1406
     "List of nodes to assign"),
1407
    ]
1408

    
1409

    
1410
class OpGroupQuery(OpCode):
1411
  """Compute the list of node groups."""
1412
  OP_PARAMS = [
1413
    _POutputFields,
1414
    ("names", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
1415
     "Empty list to query all groups, group names otherwise"),
1416
    ]
1417

    
1418

    
1419
class OpGroupSetParams(OpCode):
1420
  """Change the parameters of a node group."""
1421
  OP_DSC_FIELD = "group_name"
1422
  OP_PARAMS = [
1423
    _PGroupName,
1424
    _PNodeGroupAllocPolicy,
1425
    _PGroupNodeParams,
1426
    ]
1427
  OP_RESULT = _TSetParamsResult
1428

    
1429

    
1430
class OpGroupRemove(OpCode):
1431
  """Remove a node group from the cluster."""
1432
  OP_DSC_FIELD = "group_name"
1433
  OP_PARAMS = [
1434
    _PGroupName,
1435
    ]
1436

    
1437

    
1438
class OpGroupRename(OpCode):
1439
  """Rename a node group in the cluster."""
1440
  OP_PARAMS = [
1441
    _PGroupName,
1442
    ("new_name", ht.NoDefault, ht.TNonEmptyString, "New group name"),
1443
    ]
1444
  OP_RESULT = ht.Comment("New group name")(ht.TNonEmptyString)
1445

    
1446

    
1447
class OpGroupEvacuate(OpCode):
1448
  """Evacuate a node group in the cluster."""
1449
  OP_DSC_FIELD = "group_name"
1450
  OP_PARAMS = [
1451
    _PGroupName,
1452
    _PEarlyRelease,
1453
    ("iallocator", None, ht.TMaybeString, "Iallocator for computing solution"),
1454
    ("target_groups", None, ht.TOr(ht.TNone, ht.TListOf(ht.TNonEmptyString)),
1455
     "Destination group names or UUIDs"),
1456
    ]
1457
  OP_RESULT = TJobIdListOnly
1458

    
1459

    
1460
# OS opcodes
1461
class OpOsDiagnose(OpCode):
1462
  """Compute the list of guest operating systems."""
1463
  OP_PARAMS = [
1464
    _POutputFields,
1465
    ("names", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
1466
     "Which operating systems to diagnose"),
1467
    ]
1468

    
1469

    
1470
# Exports opcodes
1471
class OpBackupQuery(OpCode):
1472
  """Compute the list of exported images."""
1473
  OP_PARAMS = [
1474
    _PUseLocking,
1475
    ("nodes", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
1476
     "Empty list to query all nodes, node names otherwise"),
1477
    ]
1478

    
1479

    
1480
class OpBackupPrepare(OpCode):
1481
  """Prepares an instance export.
1482

1483
  @ivar instance_name: Instance name
1484
  @ivar mode: Export mode (one of L{constants.EXPORT_MODES})
1485

1486
  """
1487
  OP_DSC_FIELD = "instance_name"
1488
  OP_PARAMS = [
1489
    _PInstanceName,
1490
    ("mode", ht.NoDefault, ht.TElemOf(constants.EXPORT_MODES),
1491
     "Export mode"),
1492
    ]
1493

    
1494

    
1495
class OpBackupExport(OpCode):
1496
  """Export an instance.
1497

1498
  For local exports, the export destination is the node name. For remote
1499
  exports, the export destination is a list of tuples, each consisting of
1500
  hostname/IP address, port, HMAC and HMAC salt. The HMAC is calculated using
1501
  the cluster domain secret over the value "${index}:${hostname}:${port}". The
1502
  destination X509 CA must be a signed certificate.
1503

1504
  @ivar mode: Export mode (one of L{constants.EXPORT_MODES})
1505
  @ivar target_node: Export destination
1506
  @ivar x509_key_name: X509 key to use (remote export only)
1507
  @ivar destination_x509_ca: Destination X509 CA in PEM format (remote export
1508
                             only)
1509

1510
  """
1511
  OP_DSC_FIELD = "instance_name"
1512
  OP_PARAMS = [
1513
    _PInstanceName,
1514
    _PShutdownTimeout,
1515
    # TODO: Rename target_node as it changes meaning for different export modes
1516
    # (e.g. "destination")
1517
    ("target_node", ht.NoDefault, ht.TOr(ht.TNonEmptyString, ht.TList),
1518
     "Destination information, depends on export mode"),
1519
    ("shutdown", True, ht.TBool, "Whether to shutdown instance before export"),
1520
    ("remove_instance", False, ht.TBool,
1521
     "Whether to remove instance after export"),
1522
    ("ignore_remove_failures", False, ht.TBool,
1523
     "Whether to ignore failures while removing instances"),
1524
    ("mode", constants.EXPORT_MODE_LOCAL, ht.TElemOf(constants.EXPORT_MODES),
1525
     "Export mode"),
1526
    ("x509_key_name", None, ht.TOr(ht.TList, ht.TNone),
1527
     "Name of X509 key (remote export only)"),
1528
    ("destination_x509_ca", None, ht.TMaybeString,
1529
     "Destination X509 CA (remote export only)"),
1530
    ]
1531

    
1532

    
1533
class OpBackupRemove(OpCode):
1534
  """Remove an instance's export."""
1535
  OP_DSC_FIELD = "instance_name"
1536
  OP_PARAMS = [
1537
    _PInstanceName,
1538
    ]
1539

    
1540

    
1541
# Tags opcodes
1542
class OpTagsGet(OpCode):
1543
  """Returns the tags of the given object."""
1544
  OP_DSC_FIELD = "name"
1545
  OP_PARAMS = [
1546
    _PTagKind,
1547
    # Name is only meaningful for nodes and instances
1548
    ("name", ht.NoDefault, ht.TMaybeString, None),
1549
    ]
1550

    
1551

    
1552
class OpTagsSearch(OpCode):
1553
  """Searches the tags in the cluster for a given pattern."""
1554
  OP_DSC_FIELD = "pattern"
1555
  OP_PARAMS = [
1556
    ("pattern", ht.NoDefault, ht.TNonEmptyString, None),
1557
    ]
1558

    
1559

    
1560
class OpTagsSet(OpCode):
1561
  """Add a list of tags on a given object."""
1562
  OP_PARAMS = [
1563
    _PTagKind,
1564
    _PTags,
1565
    # Name is only meaningful for nodes and instances
1566
    ("name", ht.NoDefault, ht.TMaybeString, None),
1567
    ]
1568

    
1569

    
1570
class OpTagsDel(OpCode):
1571
  """Remove a list of tags from a given object."""
1572
  OP_PARAMS = [
1573
    _PTagKind,
1574
    _PTags,
1575
    # Name is only meaningful for nodes and instances
1576
    ("name", ht.NoDefault, ht.TMaybeString, None),
1577
    ]
1578

    
1579

    
1580
# Test opcodes
1581
class OpTestDelay(OpCode):
1582
  """Sleeps for a configured amount of time.
1583

1584
  This is used just for debugging and testing.
1585

1586
  Parameters:
1587
    - duration: the time to sleep
1588
    - on_master: if true, sleep on the master
1589
    - on_nodes: list of nodes in which to sleep
1590

1591
  If the on_master parameter is true, it will execute a sleep on the
1592
  master (before any node sleep).
1593

1594
  If the on_nodes list is not empty, it will sleep on those nodes
1595
  (after the sleep on the master, if that is enabled).
1596

1597
  As an additional feature, the case of duration < 0 will be reported
1598
  as an execution error, so this opcode can be used as a failure
1599
  generator. The case of duration == 0 will not be treated specially.
1600

1601
  """
1602
  OP_DSC_FIELD = "duration"
1603
  OP_PARAMS = [
1604
    ("duration", ht.NoDefault, ht.TNumber, None),
1605
    ("on_master", True, ht.TBool, None),
1606
    ("on_nodes", ht.EmptyList, ht.TListOf(ht.TNonEmptyString), None),
1607
    ("repeat", 0, ht.TPositiveInt, None),
1608
    ]
1609

    
1610

    
1611
class OpTestAllocator(OpCode):
1612
  """Allocator framework testing.
1613

1614
  This opcode has two modes:
1615
    - gather and return allocator input for a given mode (allocate new
1616
      or replace secondary) and a given instance definition (direction
1617
      'in')
1618
    - run a selected allocator for a given operation (as above) and
1619
      return the allocator output (direction 'out')
1620

1621
  """
1622
  OP_DSC_FIELD = "allocator"
1623
  OP_PARAMS = [
1624
    ("direction", ht.NoDefault,
1625
     ht.TElemOf(constants.VALID_IALLOCATOR_DIRECTIONS), None),
1626
    ("mode", ht.NoDefault, ht.TElemOf(constants.VALID_IALLOCATOR_MODES), None),
1627
    ("name", ht.NoDefault, ht.TNonEmptyString, None),
1628
    ("nics", ht.NoDefault, ht.TOr(ht.TNone, ht.TListOf(
1629
     ht.TDictOf(ht.TElemOf([constants.INIC_MAC, constants.INIC_IP, "bridge"]),
1630
                ht.TOr(ht.TNone, ht.TNonEmptyString)))), None),
1631
    ("disks", ht.NoDefault, ht.TOr(ht.TNone, ht.TList), None),
1632
    ("hypervisor", None, ht.TMaybeString, None),
1633
    ("allocator", None, ht.TMaybeString, None),
1634
    ("tags", ht.EmptyList, ht.TListOf(ht.TNonEmptyString), None),
1635
    ("memory", None, ht.TOr(ht.TNone, ht.TPositiveInt), None),
1636
    ("vcpus", None, ht.TOr(ht.TNone, ht.TPositiveInt), None),
1637
    ("os", None, ht.TMaybeString, None),
1638
    ("disk_template", None, ht.TMaybeString, None),
1639
    ("instances", None, ht.TOr(ht.TNone, ht.TListOf(ht.TNonEmptyString)),
1640
     None),
1641
    ("evac_mode", None,
1642
     ht.TOr(ht.TNone, ht.TElemOf(constants.IALLOCATOR_NEVAC_MODES)), None),
1643
    ("target_groups", None, ht.TOr(ht.TNone, ht.TListOf(ht.TNonEmptyString)),
1644
     None),
1645
    ]
1646

    
1647

    
1648
class OpTestJqueue(OpCode):
1649
  """Utility opcode to test some aspects of the job queue.
1650

1651
  """
1652
  OP_PARAMS = [
1653
    ("notify_waitlock", False, ht.TBool, None),
1654
    ("notify_exec", False, ht.TBool, None),
1655
    ("log_messages", ht.EmptyList, ht.TListOf(ht.TString), None),
1656
    ("fail", False, ht.TBool, None),
1657
    ]
1658

    
1659

    
1660
class OpTestDummy(OpCode):
1661
  """Utility opcode used by unittests.
1662

1663
  """
1664
  OP_PARAMS = [
1665
    ("result", ht.NoDefault, ht.NoType, None),
1666
    ("messages", ht.NoDefault, ht.NoType, None),
1667
    ("fail", ht.NoDefault, ht.NoType, None),
1668
    ("submit_jobs", None, ht.NoType, None),
1669
    ]
1670
  WITH_LU = False
1671

    
1672

    
1673
def _GetOpList():
1674
  """Returns list of all defined opcodes.
1675

1676
  Does not eliminate duplicates by C{OP_ID}.
1677

1678
  """
1679
  return [v for v in globals().values()
1680
          if (isinstance(v, type) and issubclass(v, OpCode) and
1681
              hasattr(v, "OP_ID") and v is not OpCode)]
1682

    
1683

    
1684
OP_MAPPING = dict((v.OP_ID, v) for v in _GetOpList())