Statistics
| Branch: | Tag: | Revision:

root / lib / opcodes.py @ 8bc17ebb

History | View | Annotate | Download (66.1 kB)

1
#
2
#
3

    
4
# Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011, 2012 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
import ipaddr
39

    
40
from ganeti import constants
41
from ganeti import errors
42
from ganeti import ht
43
from ganeti import objects
44
from ganeti import objectutils
45

    
46

    
47
# Common opcode attributes
48

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

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

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

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

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

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

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

    
75
#: Migration type (live/non-live)
76
_PMigrationMode = ("mode", None,
77
                   ht.TMaybe(ht.TElemOf(constants.HT_MIGRATION_MODES)),
78
                   "Migration mode")
79

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

    
84
#: Tag type
85
_PTagKind = ("kind", ht.NoDefault, ht.TElemOf(constants.VALID_TAG_TYPES),
86
             "Tag kind")
87

    
88
#: List of tag strings
89
_PTags = ("tags", ht.NoDefault, ht.TListOf(ht.TNonEmptyString),
90
          "List of tag names")
91

    
92
_PForceVariant = ("force_variant", False, ht.TBool,
93
                  "Whether to force an unknown OS variant")
94

    
95
_PWaitForSync = ("wait_for_sync", True, ht.TBool,
96
                 "Whether to wait for the disk to synchronize")
97

    
98
_PWaitForSyncFalse = ("wait_for_sync", False, ht.TBool,
99
                      "Whether to wait for the disk to synchronize"
100
                      " (defaults to false)")
101

    
102
_PIgnoreConsistency = ("ignore_consistency", False, ht.TBool,
103
                       "Whether to ignore disk consistency")
104

    
105
_PStorageName = ("name", ht.NoDefault, ht.TMaybeString, "Storage name")
106

    
107
_PUseLocking = ("use_locking", False, ht.TBool,
108
                "Whether to use synchronization")
109

    
110
_PNameCheck = ("name_check", True, ht.TBool, "Whether to check name")
111

    
112
_PNodeGroupAllocPolicy = \
113
  ("alloc_policy", None,
114
   ht.TMaybe(ht.TElemOf(constants.VALID_ALLOC_POLICIES)),
115
   "Instance allocation policy")
116

    
117
_PGroupNodeParams = ("ndparams", None, ht.TMaybeDict,
118
                     "Default node parameters for group")
119

    
120
_PQueryWhat = ("what", ht.NoDefault, ht.TElemOf(constants.QR_VIA_OP),
121
               "Resource(s) to query for")
122

    
123
_PEarlyRelease = ("early_release", False, ht.TBool,
124
                  "Whether to release locks as soon as possible")
125

    
126
_PIpCheckDoc = "Whether to ensure instance's IP address is inactive"
127

    
128
#: Do not remember instance state changes
129
_PNoRemember = ("no_remember", False, ht.TBool,
130
                "Do not remember the state change")
131

    
132
#: Target node for instance migration/failover
133
_PMigrationTargetNode = ("target_node", None, ht.TMaybeString,
134
                         "Target node for shared-storage instances")
135

    
136
_PStartupPaused = ("startup_paused", False, ht.TBool,
137
                   "Pause instance at startup")
138

    
139
_PVerbose = ("verbose", False, ht.TBool, "Verbose mode")
140

    
141
# Parameters for cluster verification
142
_PDebugSimulateErrors = ("debug_simulate_errors", False, ht.TBool,
143
                         "Whether to simulate errors (useful for debugging)")
144
_PErrorCodes = ("error_codes", False, ht.TBool, "Error codes")
145
_PSkipChecks = ("skip_checks", ht.EmptyList,
146
                ht.TListOf(ht.TElemOf(constants.VERIFY_OPTIONAL_CHECKS)),
147
                "Which checks to skip")
148
_PIgnoreErrors = ("ignore_errors", ht.EmptyList,
149
                  ht.TListOf(ht.TElemOf(constants.CV_ALL_ECODES_STRINGS)),
150
                  "List of error codes that should be treated as warnings")
151

    
152
# Disk parameters
153
_PDiskParams = \
154
  ("diskparams", None,
155
   ht.TMaybe(ht.TDictOf(ht.TElemOf(constants.DISK_TEMPLATES), ht.TDict)),
156
   "Disk templates' parameter defaults")
157

    
158
# Parameters for node resource model
159
_PHvState = ("hv_state", None, ht.TMaybeDict, "Set hypervisor states")
160
_PDiskState = ("disk_state", None, ht.TMaybeDict, "Set disk states")
161

    
162
#: Opportunistic locking
163
_POpportunisticLocking = \
164
  ("opportunistic_locking", False, ht.TBool,
165
   ("Whether to employ opportunistic locking for nodes, meaning nodes"
166
    " already locked by another opcode won't be considered for instance"
167
    " allocation (only when an iallocator is used)"))
168

    
169
_PIgnoreIpolicy = ("ignore_ipolicy", False, ht.TBool,
170
                   "Whether to ignore ipolicy violations")
171

    
172
# Allow runtime changes while migrating
173
_PAllowRuntimeChgs = ("allow_runtime_changes", True, ht.TBool,
174
                      "Allow runtime changes (eg. memory ballooning)")
175

    
176
#: IAllocator field builder
177
_PIAllocFromDesc = lambda desc: ("iallocator", None, ht.TMaybeString, desc)
178

    
179
#: a required network name
180
_PNetworkName = ("network_name", ht.NoDefault, ht.TNonEmptyString,
181
                 "Set network name")
182

    
183
#: OP_ID conversion regular expression
184
_OPID_RE = re.compile("([a-z])([A-Z])")
185

    
186
#: Utility function for L{OpClusterSetParams}
187
_TestClusterOsListItem = \
188
  ht.TAnd(ht.TIsLength(2), ht.TItems([
189
    ht.TElemOf(constants.DDMS_VALUES),
190
    ht.TNonEmptyString,
191
    ]))
192

    
193
_TestClusterOsList = ht.TMaybeListOf(_TestClusterOsListItem)
194

    
195
# TODO: Generate check from constants.INIC_PARAMS_TYPES
196
#: Utility function for testing NIC definitions
197
_TestNicDef = \
198
  ht.Comment("NIC parameters")(ht.TDictOf(ht.TElemOf(constants.INIC_PARAMS),
199
                                          ht.TMaybeString))
200

    
201
_TSetParamsResultItemItems = [
202
  ht.Comment("name of changed parameter")(ht.TNonEmptyString),
203
  ht.Comment("new value")(ht.TAny),
204
  ]
205

    
206
_TSetParamsResult = \
207
  ht.TListOf(ht.TAnd(ht.TIsLength(len(_TSetParamsResultItemItems)),
208
                     ht.TItems(_TSetParamsResultItemItems)))
209

    
210
# In the disks option we can provide arbitrary parameters too, which
211
# we may not be able to validate at this level, so we just check the
212
# format of the dict here and the checks concerning IDISK_PARAMS will
213
# happen at the LU level
214
_TDiskParams = \
215
  ht.Comment("Disk parameters")(ht.TDictOf(ht.TNonEmptyString,
216
                                           ht.TOr(ht.TNonEmptyString, ht.TInt)))
217

    
218
_TQueryRow = \
219
  ht.TListOf(ht.TAnd(ht.TIsLength(2),
220
                     ht.TItems([ht.TElemOf(constants.RS_ALL),
221
                                ht.TAny])))
222

    
223
_TQueryResult = ht.TListOf(_TQueryRow)
224

    
225
_TOldQueryRow = ht.TListOf(ht.TAny)
226

    
227
_TOldQueryResult = ht.TListOf(_TOldQueryRow)
228

    
229

    
230
_SUMMARY_PREFIX = {
231
  "CLUSTER_": "C_",
232
  "GROUP_": "G_",
233
  "NODE_": "N_",
234
  "INSTANCE_": "I_",
235
  }
236

    
237
#: Attribute name for dependencies
238
DEPEND_ATTR = "depends"
239

    
240
#: Attribute name for comment
241
COMMENT_ATTR = "comment"
242

    
243

    
244
def _NameToId(name):
245
  """Convert an opcode class name to an OP_ID.
246

247
  @type name: string
248
  @param name: the class name, as OpXxxYyy
249
  @rtype: string
250
  @return: the name in the OP_XXXX_YYYY format
251

252
  """
253
  if not name.startswith("Op"):
254
    return None
255
  # Note: (?<=[a-z])(?=[A-Z]) would be ideal, since it wouldn't
256
  # consume any input, and hence we would just have all the elements
257
  # in the list, one by one; but it seems that split doesn't work on
258
  # non-consuming input, hence we have to process the input string a
259
  # bit
260
  name = _OPID_RE.sub(r"\1,\2", name)
261
  elems = name.split(",")
262
  return "_".join(n.upper() for n in elems)
263

    
264

    
265
def _GenerateObjectTypeCheck(obj, fields_types):
266
  """Helper to generate type checks for objects.
267

268
  @param obj: The object to generate type checks
269
  @param fields_types: The fields and their types as a dict
270
  @return: A ht type check function
271

272
  """
273
  assert set(obj.GetAllSlots()) == set(fields_types.keys()), \
274
    "%s != %s" % (set(obj.GetAllSlots()), set(fields_types.keys()))
275
  return ht.TStrictDict(True, True, fields_types)
276

    
277

    
278
_TQueryFieldDef = \
279
  _GenerateObjectTypeCheck(objects.QueryFieldDefinition, {
280
    "name": ht.TNonEmptyString,
281
    "title": ht.TNonEmptyString,
282
    "kind": ht.TElemOf(constants.QFT_ALL),
283
    "doc": ht.TNonEmptyString,
284
    })
285

    
286

    
287
def RequireFileStorage():
288
  """Checks that file storage is enabled.
289

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

293
  @raise errors.OpPrereqError: when file storage is disabled
294

295
  """
296
  if not constants.ENABLE_FILE_STORAGE:
297
    raise errors.OpPrereqError("File storage disabled at configure time",
298
                               errors.ECODE_INVAL)
299

    
300

    
301
def RequireSharedFileStorage():
302
  """Checks that shared file storage is enabled.
303

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

307
  @raise errors.OpPrereqError: when shared file storage is disabled
308

309
  """
310
  if not constants.ENABLE_SHARED_FILE_STORAGE:
311
    raise errors.OpPrereqError("Shared file storage disabled at"
312
                               " configure time", errors.ECODE_INVAL)
313

    
314

    
315
@ht.WithDesc("CheckFileStorage")
316
def _CheckFileStorage(value):
317
  """Ensures file storage is enabled if used.
318

319
  """
320
  if value == constants.DT_FILE:
321
    RequireFileStorage()
322
  elif value == constants.DT_SHARED_FILE:
323
    RequireSharedFileStorage()
324
  return True
325

    
326

    
327
def _BuildDiskTemplateCheck(accept_none):
328
  """Builds check for disk template.
329

330
  @type accept_none: bool
331
  @param accept_none: whether to accept None as a correct value
332
  @rtype: callable
333

334
  """
335
  template_check = ht.TElemOf(constants.DISK_TEMPLATES)
336

    
337
  if accept_none:
338
    template_check = ht.TMaybe(template_check)
339

    
340
  return ht.TAnd(template_check, _CheckFileStorage)
341

    
342

    
343
def _CheckStorageType(storage_type):
344
  """Ensure a given storage type is valid.
345

346
  """
347
  if storage_type not in constants.VALID_STORAGE_TYPES:
348
    raise errors.OpPrereqError("Unknown storage type: %s" % storage_type,
349
                               errors.ECODE_INVAL)
350
  if storage_type == constants.ST_FILE:
351
    # TODO: What about shared file storage?
352
    RequireFileStorage()
353
  return True
354

    
355

    
356
#: Storage type parameter
357
_PStorageType = ("storage_type", ht.NoDefault, _CheckStorageType,
358
                 "Storage type")
359

    
360
_CheckNetworkType = ht.TElemOf(constants.NETWORK_VALID_TYPES)
361

    
362

    
363
@ht.WithDesc("IPv4 network")
364
def _CheckCIDRNetNotation(value):
365
  """Ensure a given CIDR notation type is valid.
366

367
  """
368
  try:
369
    ipaddr.IPv4Network(value)
370
  except ipaddr.AddressValueError:
371
    return False
372
  return True
373

    
374

    
375
@ht.WithDesc("IPv4 address")
376
def _CheckCIDRAddrNotation(value):
377
  """Ensure a given CIDR notation type is valid.
378

379
  """
380
  try:
381
    ipaddr.IPv4Address(value)
382
  except ipaddr.AddressValueError:
383
    return False
384
  return True
385

    
386

    
387
@ht.WithDesc("IPv6 address")
388
def _CheckCIDR6AddrNotation(value):
389
  """Ensure a given CIDR notation type is valid.
390

391
  """
392
  try:
393
    ipaddr.IPv6Address(value)
394
  except ipaddr.AddressValueError:
395
    return False
396
  return True
397

    
398

    
399
@ht.WithDesc("IPv6 network")
400
def _CheckCIDR6NetNotation(value):
401
  """Ensure a given CIDR notation type is valid.
402

403
  """
404
  try:
405
    ipaddr.IPv6Network(value)
406
  except ipaddr.AddressValueError:
407
    return False
408
  return True
409

    
410

    
411
_TIpAddress4 = ht.TAnd(ht.TString, _CheckCIDRAddrNotation)
412
_TIpAddress6 = ht.TAnd(ht.TString, _CheckCIDR6AddrNotation)
413
_TIpNetwork4 = ht.TAnd(ht.TString, _CheckCIDRNetNotation)
414
_TIpNetwork6 = ht.TAnd(ht.TString, _CheckCIDR6NetNotation)
415
_TMaybeAddr4List = ht.TMaybe(ht.TListOf(_TIpAddress4))
416

    
417

    
418
class _AutoOpParamSlots(objectutils.AutoSlots):
419
  """Meta class for opcode definitions.
420

421
  """
422
  def __new__(mcs, name, bases, attrs):
423
    """Called when a class should be created.
424

425
    @param mcs: The meta class
426
    @param name: Name of created class
427
    @param bases: Base classes
428
    @type attrs: dict
429
    @param attrs: Class attributes
430

431
    """
432
    assert "OP_ID" not in attrs, "Class '%s' defining OP_ID" % name
433

    
434
    slots = mcs._GetSlots(attrs)
435
    assert "OP_DSC_FIELD" not in attrs or attrs["OP_DSC_FIELD"] in slots, \
436
      "Class '%s' uses unknown field in OP_DSC_FIELD" % name
437
    assert ("OP_DSC_FORMATTER" not in attrs or
438
            callable(attrs["OP_DSC_FORMATTER"])), \
439
      ("Class '%s' uses non-callable in OP_DSC_FORMATTER (%s)" %
440
       (name, type(attrs["OP_DSC_FORMATTER"])))
441

    
442
    attrs["OP_ID"] = _NameToId(name)
443

    
444
    return objectutils.AutoSlots.__new__(mcs, name, bases, attrs)
445

    
446
  @classmethod
447
  def _GetSlots(mcs, attrs):
448
    """Build the slots out of OP_PARAMS.
449

450
    """
451
    # Always set OP_PARAMS to avoid duplicates in BaseOpCode.GetAllParams
452
    params = attrs.setdefault("OP_PARAMS", [])
453

    
454
    # Use parameter names as slots
455
    return [pname for (pname, _, _, _) in params]
456

    
457

    
458
class BaseOpCode(objectutils.ValidatedSlots):
459
  """A simple serializable object.
460

461
  This object serves as a parent class for OpCode without any custom
462
  field handling.
463

464
  """
465
  # pylint: disable=E1101
466
  # as OP_ID is dynamically defined
467
  __metaclass__ = _AutoOpParamSlots
468

    
469
  def __getstate__(self):
470
    """Generic serializer.
471

472
    This method just returns the contents of the instance as a
473
    dictionary.
474

475
    @rtype:  C{dict}
476
    @return: the instance attributes and their values
477

478
    """
479
    state = {}
480
    for name in self.GetAllSlots():
481
      if hasattr(self, name):
482
        state[name] = getattr(self, name)
483
    return state
484

    
485
  def __setstate__(self, state):
486
    """Generic unserializer.
487

488
    This method just restores from the serialized state the attributes
489
    of the current instance.
490

491
    @param state: the serialized opcode data
492
    @type state:  C{dict}
493

494
    """
495
    if not isinstance(state, dict):
496
      raise ValueError("Invalid data to __setstate__: expected dict, got %s" %
497
                       type(state))
498

    
499
    for name in self.GetAllSlots():
500
      if name not in state and hasattr(self, name):
501
        delattr(self, name)
502

    
503
    for name in state:
504
      setattr(self, name, state[name])
505

    
506
  @classmethod
507
  def GetAllParams(cls):
508
    """Compute list of all parameters for an opcode.
509

510
    """
511
    slots = []
512
    for parent in cls.__mro__:
513
      slots.extend(getattr(parent, "OP_PARAMS", []))
514
    return slots
515

    
516
  def Validate(self, set_defaults): # pylint: disable=W0221
517
    """Validate opcode parameters, optionally setting default values.
518

519
    @type set_defaults: bool
520
    @param set_defaults: Whether to set default values
521
    @raise errors.OpPrereqError: When a parameter value doesn't match
522
                                 requirements
523

524
    """
525
    for (attr_name, default, test, _) in self.GetAllParams():
526
      assert test == ht.NoType or callable(test)
527

    
528
      if not hasattr(self, attr_name):
529
        if default == ht.NoDefault:
530
          raise errors.OpPrereqError("Required parameter '%s.%s' missing" %
531
                                     (self.OP_ID, attr_name),
532
                                     errors.ECODE_INVAL)
533
        elif set_defaults:
534
          if callable(default):
535
            dval = default()
536
          else:
537
            dval = default
538
          setattr(self, attr_name, dval)
539

    
540
      if test == ht.NoType:
541
        # no tests here
542
        continue
543

    
544
      if set_defaults or hasattr(self, attr_name):
545
        attr_val = getattr(self, attr_name)
546
        if not test(attr_val):
547
          logging.error("OpCode %s, parameter %s, has invalid type %s/value"
548
                        " '%s' expecting type %s",
549
                        self.OP_ID, attr_name, type(attr_val), attr_val, test)
550
          raise errors.OpPrereqError("Parameter '%s.%s' fails validation" %
551
                                     (self.OP_ID, attr_name),
552
                                     errors.ECODE_INVAL)
553

    
554

    
555
def _BuildJobDepCheck(relative):
556
  """Builds check for job dependencies (L{DEPEND_ATTR}).
557

558
  @type relative: bool
559
  @param relative: Whether to accept relative job IDs (negative)
560
  @rtype: callable
561

562
  """
563
  if relative:
564
    job_id = ht.TOr(ht.TJobId, ht.TRelativeJobId)
565
  else:
566
    job_id = ht.TJobId
567

    
568
  job_dep = \
569
    ht.TAnd(ht.TOr(ht.TList, ht.TTuple),
570
            ht.TIsLength(2),
571
            ht.TItems([job_id,
572
                       ht.TListOf(ht.TElemOf(constants.JOBS_FINALIZED))]))
573

    
574
  return ht.TMaybeListOf(job_dep)
575

    
576

    
577
TNoRelativeJobDependencies = _BuildJobDepCheck(False)
578

    
579
#: List of submission status and job ID as returned by C{SubmitManyJobs}
580
_TJobIdListItem = \
581
  ht.TAnd(ht.TIsLength(2),
582
          ht.TItems([ht.Comment("success")(ht.TBool),
583
                     ht.Comment("Job ID if successful, error message"
584
                                " otherwise")(ht.TOr(ht.TString,
585
                                                     ht.TJobId))]))
586
TJobIdList = ht.TListOf(_TJobIdListItem)
587

    
588
#: Result containing only list of submitted jobs
589
TJobIdListOnly = ht.TStrictDict(True, True, {
590
  constants.JOB_IDS_KEY: ht.Comment("List of submitted jobs")(TJobIdList),
591
  })
592

    
593

    
594
class OpCode(BaseOpCode):
595
  """Abstract OpCode.
596

597
  This is the root of the actual OpCode hierarchy. All clases derived
598
  from this class should override OP_ID.
599

600
  @cvar OP_ID: The ID of this opcode. This should be unique amongst all
601
               children of this class.
602
  @cvar OP_DSC_FIELD: The name of a field whose value will be included in the
603
                      string returned by Summary(); see the docstring of that
604
                      method for details).
605
  @cvar OP_DSC_FORMATTER: A callable that should format the OP_DSC_FIELD; if
606
                          not present, then the field will be simply converted
607
                          to string
608
  @cvar OP_PARAMS: List of opcode attributes, the default values they should
609
                   get if not already defined, and types they must match.
610
  @cvar OP_RESULT: Callable to verify opcode result
611
  @cvar WITH_LU: Boolean that specifies whether this should be included in
612
      mcpu's dispatch table
613
  @ivar dry_run: Whether the LU should be run in dry-run mode, i.e. just
614
                 the check steps
615
  @ivar priority: Opcode priority for queue
616

617
  """
618
  # pylint: disable=E1101
619
  # as OP_ID is dynamically defined
620
  WITH_LU = True
621
  OP_PARAMS = [
622
    ("dry_run", None, ht.TMaybeBool, "Run checks only, don't execute"),
623
    ("debug_level", None, ht.TMaybe(ht.TNonNegativeInt), "Debug level"),
624
    ("priority", constants.OP_PRIO_DEFAULT,
625
     ht.TElemOf(constants.OP_PRIO_SUBMIT_VALID), "Opcode priority"),
626
    (DEPEND_ATTR, None, _BuildJobDepCheck(True),
627
     "Job dependencies; if used through ``SubmitManyJobs`` relative (negative)"
628
     " job IDs can be used; see :doc:`design document <design-chained-jobs>`"
629
     " for details"),
630
    (COMMENT_ATTR, None, ht.TMaybeString,
631
     "Comment describing the purpose of the opcode"),
632
    ]
633
  OP_RESULT = None
634

    
635
  def __getstate__(self):
636
    """Specialized getstate for opcodes.
637

638
    This method adds to the state dictionary the OP_ID of the class,
639
    so that on unload we can identify the correct class for
640
    instantiating the opcode.
641

642
    @rtype:   C{dict}
643
    @return:  the state as a dictionary
644

645
    """
646
    data = BaseOpCode.__getstate__(self)
647
    data["OP_ID"] = self.OP_ID
648
    return data
649

    
650
  @classmethod
651
  def LoadOpCode(cls, data):
652
    """Generic load opcode method.
653

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

658
    @type data:  C{dict}
659
    @param data: the serialized opcode
660

661
    """
662
    if not isinstance(data, dict):
663
      raise ValueError("Invalid data to LoadOpCode (%s)" % type(data))
664
    if "OP_ID" not in data:
665
      raise ValueError("Invalid data to LoadOpcode, missing OP_ID")
666
    op_id = data["OP_ID"]
667
    op_class = None
668
    if op_id in OP_MAPPING:
669
      op_class = OP_MAPPING[op_id]
670
    else:
671
      raise ValueError("Invalid data to LoadOpCode: OP_ID %s unsupported" %
672
                       op_id)
673
    op = op_class()
674
    new_data = data.copy()
675
    del new_data["OP_ID"]
676
    op.__setstate__(new_data)
677
    return op
678

    
679
  def Summary(self):
680
    """Generates a summary description of this opcode.
681

682
    The summary is the value of the OP_ID attribute (without the "OP_"
683
    prefix), plus the value of the OP_DSC_FIELD attribute, if one was
684
    defined; this field should allow to easily identify the operation
685
    (for an instance creation job, e.g., it would be the instance
686
    name).
687

688
    """
689
    assert self.OP_ID is not None and len(self.OP_ID) > 3
690
    # all OP_ID start with OP_, we remove that
691
    txt = self.OP_ID[3:]
692
    field_name = getattr(self, "OP_DSC_FIELD", None)
693
    if field_name:
694
      field_value = getattr(self, field_name, None)
695
      field_formatter = getattr(self, "OP_DSC_FORMATTER", None)
696
      if callable(field_formatter):
697
        field_value = field_formatter(field_value)
698
      elif isinstance(field_value, (list, tuple)):
699
        field_value = ",".join(str(i) for i in field_value)
700
      txt = "%s(%s)" % (txt, field_value)
701
    return txt
702

    
703
  def TinySummary(self):
704
    """Generates a compact summary description of the opcode.
705

706
    """
707
    assert self.OP_ID.startswith("OP_")
708

    
709
    text = self.OP_ID[3:]
710

    
711
    for (prefix, supplement) in _SUMMARY_PREFIX.items():
712
      if text.startswith(prefix):
713
        return supplement + text[len(prefix):]
714

    
715
    return text
716

    
717

    
718
# cluster opcodes
719

    
720
class OpClusterPostInit(OpCode):
721
  """Post cluster initialization.
722

723
  This opcode does not touch the cluster at all. Its purpose is to run hooks
724
  after the cluster has been initialized.
725

726
  """
727
  OP_RESULT = ht.TBool
728

    
729

    
730
class OpClusterDestroy(OpCode):
731
  """Destroy the cluster.
732

733
  This opcode has no other parameters. All the state is irreversibly
734
  lost after the execution of this opcode.
735

736
  """
737
  OP_RESULT = ht.TNonEmptyString
738

    
739

    
740
class OpClusterQuery(OpCode):
741
  """Query cluster information."""
742
  OP_RESULT = ht.TDictOf(ht.TNonEmptyString, ht.TAny)
743

    
744

    
745
class OpClusterVerify(OpCode):
746
  """Submits all jobs necessary to verify the cluster.
747

748
  """
749
  OP_PARAMS = [
750
    _PDebugSimulateErrors,
751
    _PErrorCodes,
752
    _PSkipChecks,
753
    _PIgnoreErrors,
754
    _PVerbose,
755
    ("group_name", None, ht.TMaybeString, "Group to verify"),
756
    ]
757
  OP_RESULT = TJobIdListOnly
758

    
759

    
760
class OpClusterVerifyConfig(OpCode):
761
  """Verify the cluster config.
762

763
  """
764
  OP_PARAMS = [
765
    _PDebugSimulateErrors,
766
    _PErrorCodes,
767
    _PIgnoreErrors,
768
    _PVerbose,
769
    ]
770
  OP_RESULT = ht.TBool
771

    
772

    
773
class OpClusterVerifyGroup(OpCode):
774
  """Run verify on a node group from the cluster.
775

776
  @type skip_checks: C{list}
777
  @ivar skip_checks: steps to be skipped from the verify process; this
778
                     needs to be a subset of
779
                     L{constants.VERIFY_OPTIONAL_CHECKS}; currently
780
                     only L{constants.VERIFY_NPLUSONE_MEM} can be passed
781

782
  """
783
  OP_DSC_FIELD = "group_name"
784
  OP_PARAMS = [
785
    _PGroupName,
786
    _PDebugSimulateErrors,
787
    _PErrorCodes,
788
    _PSkipChecks,
789
    _PIgnoreErrors,
790
    _PVerbose,
791
    ]
792
  OP_RESULT = ht.TBool
793

    
794

    
795
class OpClusterVerifyDisks(OpCode):
796
  """Verify the cluster disks.
797

798
  """
799
  OP_RESULT = TJobIdListOnly
800

    
801

    
802
class OpGroupVerifyDisks(OpCode):
803
  """Verifies the status of all disks in a node group.
804

805
  Result: a tuple of three elements:
806
    - dict of node names with issues (values: error msg)
807
    - list of instances with degraded disks (that should be activated)
808
    - dict of instances with missing logical volumes (values: (node, vol)
809
      pairs with details about the missing volumes)
810

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

816
  Note that only instances that are drbd-based are taken into
817
  consideration. This might need to be revisited in the future.
818

819
  """
820
  OP_DSC_FIELD = "group_name"
821
  OP_PARAMS = [
822
    _PGroupName,
823
    ]
824
  OP_RESULT = \
825
    ht.TAnd(ht.TIsLength(3),
826
            ht.TItems([ht.TDictOf(ht.TString, ht.TString),
827
                       ht.TListOf(ht.TString),
828
                       ht.TDictOf(ht.TString,
829
                                  ht.TListOf(ht.TListOf(ht.TString)))]))
830

    
831

    
832
class OpClusterRepairDiskSizes(OpCode):
833
  """Verify the disk sizes of the instances and fixes configuration
834
  mimatches.
835

836
  Parameters: optional instances list, in case we want to restrict the
837
  checks to only a subset of the instances.
838

839
  Result: a list of tuples, (instance, disk, new-size) for changed
840
  configurations.
841

842
  In normal operation, the list should be empty.
843

844
  @type instances: list
845
  @ivar instances: the list of instances to check, or empty for all instances
846

847
  """
848
  OP_PARAMS = [
849
    ("instances", ht.EmptyList, ht.TListOf(ht.TNonEmptyString), None),
850
    ]
851
  OP_RESULT = ht.TListOf(ht.TAnd(ht.TIsLength(3),
852
                                 ht.TItems([ht.TNonEmptyString,
853
                                            ht.TNonNegativeInt,
854
                                            ht.TNonNegativeInt])))
855

    
856

    
857
class OpClusterConfigQuery(OpCode):
858
  """Query cluster configuration values."""
859
  OP_PARAMS = [
860
    _POutputFields,
861
    ]
862
  OP_RESULT = ht.TListOf(ht.TAny)
863

    
864

    
865
class OpClusterRename(OpCode):
866
  """Rename the cluster.
867

868
  @type name: C{str}
869
  @ivar name: The new name of the cluster. The name and/or the master IP
870
              address will be changed to match the new name and its IP
871
              address.
872

873
  """
874
  OP_DSC_FIELD = "name"
875
  OP_PARAMS = [
876
    ("name", ht.NoDefault, ht.TNonEmptyString, None),
877
    ]
878
  OP_RESULT = ht.TNonEmptyString
879

    
880

    
881
class OpClusterSetParams(OpCode):
882
  """Change the parameters of the cluster.
883

884
  @type vg_name: C{str} or C{None}
885
  @ivar vg_name: The new volume group name or None to disable LVM usage.
886

887
  """
888
  OP_PARAMS = [
889
    _PHvState,
890
    _PDiskState,
891
    ("vg_name", None, ht.TMaybe(ht.TString), "Volume group name"),
892
    ("enabled_hypervisors", None,
893
     ht.TMaybe(ht.TAnd(ht.TListOf(ht.TElemOf(constants.HYPER_TYPES)),
894
                       ht.TTrue)),
895
     "List of enabled hypervisors"),
896
    ("hvparams", None,
897
     ht.TMaybe(ht.TDictOf(ht.TNonEmptyString, ht.TDict)),
898
     "Cluster-wide hypervisor parameter defaults, hypervisor-dependent"),
899
    ("beparams", None, ht.TMaybeDict,
900
     "Cluster-wide backend parameter defaults"),
901
    ("os_hvp", None, ht.TMaybe(ht.TDictOf(ht.TNonEmptyString, ht.TDict)),
902
     "Cluster-wide per-OS hypervisor parameter defaults"),
903
    ("osparams", None,
904
     ht.TMaybe(ht.TDictOf(ht.TNonEmptyString, ht.TDict)),
905
     "Cluster-wide OS parameter defaults"),
906
    _PDiskParams,
907
    ("candidate_pool_size", None, ht.TMaybe(ht.TPositiveInt),
908
     "Master candidate pool size"),
909
    ("uid_pool", None, ht.NoType,
910
     "Set UID pool, must be list of lists describing UID ranges (two items,"
911
     " start and end inclusive)"),
912
    ("add_uids", None, ht.NoType,
913
     "Extend UID pool, must be list of lists describing UID ranges (two"
914
     " items, start and end inclusive) to be added"),
915
    ("remove_uids", None, ht.NoType,
916
     "Shrink UID pool, must be list of lists describing UID ranges (two"
917
     " items, start and end inclusive) to be removed"),
918
    ("maintain_node_health", None, ht.TMaybeBool,
919
     "Whether to automatically maintain node health"),
920
    ("prealloc_wipe_disks", None, ht.TMaybeBool,
921
     "Whether to wipe disks before allocating them to instances"),
922
    ("nicparams", None, ht.TMaybeDict, "Cluster-wide NIC parameter defaults"),
923
    ("ndparams", None, ht.TMaybeDict, "Cluster-wide node parameter defaults"),
924
    ("ipolicy", None, ht.TMaybeDict,
925
     "Cluster-wide :ref:`instance policy <rapi-ipolicy>` specs"),
926
    ("drbd_helper", None, ht.TMaybe(ht.TString), "DRBD helper program"),
927
    ("default_iallocator", None, ht.TMaybe(ht.TString),
928
     "Default iallocator for cluster"),
929
    ("master_netdev", None, ht.TMaybe(ht.TString),
930
     "Master network device"),
931
    ("master_netmask", None, ht.TMaybe(ht.TNonNegativeInt),
932
     "Netmask of the master IP"),
933
    ("reserved_lvs", None, ht.TMaybeListOf(ht.TNonEmptyString),
934
     "List of reserved LVs"),
935
    ("hidden_os", None, _TestClusterOsList,
936
     "Modify list of hidden operating systems: each modification must have"
937
     " two items, the operation and the OS name; the operation can be"
938
     " ``%s`` or ``%s``" % (constants.DDM_ADD, constants.DDM_REMOVE)),
939
    ("blacklisted_os", None, _TestClusterOsList,
940
     "Modify list of blacklisted operating systems: each modification must"
941
     " have two items, the operation and the OS name; the operation can be"
942
     " ``%s`` or ``%s``" % (constants.DDM_ADD, constants.DDM_REMOVE)),
943
    ("use_external_mip_script", None, ht.TMaybeBool,
944
     "Whether to use an external master IP address setup script"),
945
    ]
946
  OP_RESULT = ht.TNone
947

    
948

    
949
class OpClusterRedistConf(OpCode):
950
  """Force a full push of the cluster configuration.
951

952
  """
953
  OP_RESULT = ht.TNone
954

    
955

    
956
class OpClusterActivateMasterIp(OpCode):
957
  """Activate the master IP on the master node.
958

959
  """
960
  OP_RESULT = ht.TNone
961

    
962

    
963
class OpClusterDeactivateMasterIp(OpCode):
964
  """Deactivate the master IP on the master node.
965

966
  """
967
  OP_RESULT = ht.TNone
968

    
969

    
970
class OpQuery(OpCode):
971
  """Query for resources/items.
972

973
  @ivar what: Resources to query for, must be one of L{constants.QR_VIA_OP}
974
  @ivar fields: List of fields to retrieve
975
  @ivar qfilter: Query filter
976

977
  """
978
  OP_DSC_FIELD = "what"
979
  OP_PARAMS = [
980
    _PQueryWhat,
981
    _PUseLocking,
982
    ("fields", ht.NoDefault, ht.TListOf(ht.TNonEmptyString),
983
     "Requested fields"),
984
    ("qfilter", None, ht.TMaybe(ht.TList),
985
     "Query filter"),
986
    ]
987
  OP_RESULT = \
988
    _GenerateObjectTypeCheck(objects.QueryResponse, {
989
      "fields": ht.TListOf(_TQueryFieldDef),
990
      "data": _TQueryResult,
991
      })
992

    
993

    
994
class OpQueryFields(OpCode):
995
  """Query for available resource/item fields.
996

997
  @ivar what: Resources to query for, must be one of L{constants.QR_VIA_OP}
998
  @ivar fields: List of fields to retrieve
999

1000
  """
1001
  OP_DSC_FIELD = "what"
1002
  OP_PARAMS = [
1003
    _PQueryWhat,
1004
    ("fields", None, ht.TMaybeListOf(ht.TNonEmptyString),
1005
     "Requested fields; if not given, all are returned"),
1006
    ]
1007
  OP_RESULT = \
1008
    _GenerateObjectTypeCheck(objects.QueryFieldsResponse, {
1009
      "fields": ht.TListOf(_TQueryFieldDef),
1010
      })
1011

    
1012

    
1013
class OpOobCommand(OpCode):
1014
  """Interact with OOB."""
1015
  OP_PARAMS = [
1016
    ("node_names", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
1017
     "List of nodes to run the OOB command against"),
1018
    ("command", ht.NoDefault, ht.TElemOf(constants.OOB_COMMANDS),
1019
     "OOB command to be run"),
1020
    ("timeout", constants.OOB_TIMEOUT, ht.TInt,
1021
     "Timeout before the OOB helper will be terminated"),
1022
    ("ignore_status", False, ht.TBool,
1023
     "Ignores the node offline status for power off"),
1024
    ("power_delay", constants.OOB_POWER_DELAY, ht.TNonNegativeFloat,
1025
     "Time in seconds to wait between powering on nodes"),
1026
    ]
1027
  # Fixme: Make it more specific with all the special cases in LUOobCommand
1028
  OP_RESULT = _TQueryResult
1029

    
1030

    
1031
class OpRestrictedCommand(OpCode):
1032
  """Runs a restricted command on node(s).
1033

1034
  """
1035
  OP_PARAMS = [
1036
    _PUseLocking,
1037
    ("nodes", ht.NoDefault, ht.TListOf(ht.TNonEmptyString),
1038
     "Nodes on which the command should be run (at least one)"),
1039
    ("command", ht.NoDefault, ht.TNonEmptyString,
1040
     "Command name (no parameters)"),
1041
    ]
1042

    
1043
  _RESULT_ITEMS = [
1044
    ht.Comment("success")(ht.TBool),
1045
    ht.Comment("output or error message")(ht.TString),
1046
    ]
1047

    
1048
  OP_RESULT = \
1049
    ht.TListOf(ht.TAnd(ht.TIsLength(len(_RESULT_ITEMS)),
1050
                       ht.TItems(_RESULT_ITEMS)))
1051

    
1052

    
1053
# node opcodes
1054

    
1055
class OpNodeRemove(OpCode):
1056
  """Remove a node.
1057

1058
  @type node_name: C{str}
1059
  @ivar node_name: The name of the node to remove. If the node still has
1060
                   instances on it, the operation will fail.
1061

1062
  """
1063
  OP_DSC_FIELD = "node_name"
1064
  OP_PARAMS = [
1065
    _PNodeName,
1066
    ]
1067
  OP_RESULT = ht.TNone
1068

    
1069

    
1070
class OpNodeAdd(OpCode):
1071
  """Add a node to the cluster.
1072

1073
  @type node_name: C{str}
1074
  @ivar node_name: The name of the node to add. This can be a short name,
1075
                   but it will be expanded to the FQDN.
1076
  @type primary_ip: IP address
1077
  @ivar primary_ip: The primary IP of the node. This will be ignored when the
1078
                    opcode is submitted, but will be filled during the node
1079
                    add (so it will be visible in the job query).
1080
  @type secondary_ip: IP address
1081
  @ivar secondary_ip: The secondary IP of the node. This needs to be passed
1082
                      if the cluster has been initialized in 'dual-network'
1083
                      mode, otherwise it must not be given.
1084
  @type readd: C{bool}
1085
  @ivar readd: Whether to re-add an existing node to the cluster. If
1086
               this is not passed, then the operation will abort if the node
1087
               name is already in the cluster; use this parameter to 'repair'
1088
               a node that had its configuration broken, or was reinstalled
1089
               without removal from the cluster.
1090
  @type group: C{str}
1091
  @ivar group: The node group to which this node will belong.
1092
  @type vm_capable: C{bool}
1093
  @ivar vm_capable: The vm_capable node attribute
1094
  @type master_capable: C{bool}
1095
  @ivar master_capable: The master_capable node attribute
1096

1097
  """
1098
  OP_DSC_FIELD = "node_name"
1099
  OP_PARAMS = [
1100
    _PNodeName,
1101
    _PHvState,
1102
    _PDiskState,
1103
    ("primary_ip", None, ht.NoType, "Primary IP address"),
1104
    ("secondary_ip", None, ht.TMaybeString, "Secondary IP address"),
1105
    ("readd", False, ht.TBool, "Whether node is re-added to cluster"),
1106
    ("group", None, ht.TMaybeString, "Initial node group"),
1107
    ("master_capable", None, ht.TMaybeBool,
1108
     "Whether node can become master or master candidate"),
1109
    ("vm_capable", None, ht.TMaybeBool,
1110
     "Whether node can host instances"),
1111
    ("ndparams", None, ht.TMaybeDict, "Node parameters"),
1112
    ]
1113
  OP_RESULT = ht.TNone
1114

    
1115

    
1116
class OpNodeQuery(OpCode):
1117
  """Compute the list of nodes."""
1118
  OP_PARAMS = [
1119
    _POutputFields,
1120
    _PUseLocking,
1121
    ("names", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
1122
     "Empty list to query all nodes, node names otherwise"),
1123
    ]
1124
  OP_RESULT = _TOldQueryResult
1125

    
1126

    
1127
class OpNodeQueryvols(OpCode):
1128
  """Get list of volumes on node."""
1129
  OP_PARAMS = [
1130
    _POutputFields,
1131
    ("nodes", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
1132
     "Empty list to query all nodes, node names otherwise"),
1133
    ]
1134
  OP_RESULT = ht.TListOf(ht.TAny)
1135

    
1136

    
1137
class OpNodeQueryStorage(OpCode):
1138
  """Get information on storage for node(s)."""
1139
  OP_PARAMS = [
1140
    _POutputFields,
1141
    _PStorageType,
1142
    ("nodes", ht.EmptyList, ht.TListOf(ht.TNonEmptyString), "List of nodes"),
1143
    ("name", None, ht.TMaybeString, "Storage name"),
1144
    ]
1145
  OP_RESULT = _TOldQueryResult
1146

    
1147

    
1148
class OpNodeModifyStorage(OpCode):
1149
  """Modifies the properies of a storage unit"""
1150
  OP_DSC_FIELD = "node_name"
1151
  OP_PARAMS = [
1152
    _PNodeName,
1153
    _PStorageType,
1154
    _PStorageName,
1155
    ("changes", ht.NoDefault, ht.TDict, "Requested changes"),
1156
    ]
1157
  OP_RESULT = ht.TNone
1158

    
1159

    
1160
class OpRepairNodeStorage(OpCode):
1161
  """Repairs the volume group on a node."""
1162
  OP_DSC_FIELD = "node_name"
1163
  OP_PARAMS = [
1164
    _PNodeName,
1165
    _PStorageType,
1166
    _PStorageName,
1167
    _PIgnoreConsistency,
1168
    ]
1169
  OP_RESULT = ht.TNone
1170

    
1171

    
1172
class OpNodeSetParams(OpCode):
1173
  """Change the parameters of a node."""
1174
  OP_DSC_FIELD = "node_name"
1175
  OP_PARAMS = [
1176
    _PNodeName,
1177
    _PForce,
1178
    _PHvState,
1179
    _PDiskState,
1180
    ("master_candidate", None, ht.TMaybeBool,
1181
     "Whether the node should become a master candidate"),
1182
    ("offline", None, ht.TMaybeBool,
1183
     "Whether the node should be marked as offline"),
1184
    ("drained", None, ht.TMaybeBool,
1185
     "Whether the node should be marked as drained"),
1186
    ("auto_promote", False, ht.TBool,
1187
     "Whether node(s) should be promoted to master candidate if necessary"),
1188
    ("master_capable", None, ht.TMaybeBool,
1189
     "Denote whether node can become master or master candidate"),
1190
    ("vm_capable", None, ht.TMaybeBool,
1191
     "Denote whether node can host instances"),
1192
    ("secondary_ip", None, ht.TMaybeString,
1193
     "Change node's secondary IP address"),
1194
    ("ndparams", None, ht.TMaybeDict, "Set node parameters"),
1195
    ("powered", None, ht.TMaybeBool,
1196
     "Whether the node should be marked as powered"),
1197
    ]
1198
  OP_RESULT = _TSetParamsResult
1199

    
1200

    
1201
class OpNodePowercycle(OpCode):
1202
  """Tries to powercycle a node."""
1203
  OP_DSC_FIELD = "node_name"
1204
  OP_PARAMS = [
1205
    _PNodeName,
1206
    _PForce,
1207
    ]
1208
  OP_RESULT = ht.TMaybeString
1209

    
1210

    
1211
class OpNodeMigrate(OpCode):
1212
  """Migrate all instances from a node."""
1213
  OP_DSC_FIELD = "node_name"
1214
  OP_PARAMS = [
1215
    _PNodeName,
1216
    _PMigrationMode,
1217
    _PMigrationLive,
1218
    _PMigrationTargetNode,
1219
    _PAllowRuntimeChgs,
1220
    _PIgnoreIpolicy,
1221
    _PIAllocFromDesc("Iallocator for deciding the target node"
1222
                     " for shared-storage instances"),
1223
    ]
1224
  OP_RESULT = TJobIdListOnly
1225

    
1226

    
1227
class OpNodeEvacuate(OpCode):
1228
  """Evacuate instances off a number of nodes."""
1229
  OP_DSC_FIELD = "node_name"
1230
  OP_PARAMS = [
1231
    _PEarlyRelease,
1232
    _PNodeName,
1233
    ("remote_node", None, ht.TMaybeString, "New secondary node"),
1234
    _PIAllocFromDesc("Iallocator for computing solution"),
1235
    ("mode", ht.NoDefault, ht.TElemOf(constants.NODE_EVAC_MODES),
1236
     "Node evacuation mode"),
1237
    ]
1238
  OP_RESULT = TJobIdListOnly
1239

    
1240

    
1241
# instance opcodes
1242

    
1243
class OpInstanceCreate(OpCode):
1244
  """Create an instance.
1245

1246
  @ivar instance_name: Instance name
1247
  @ivar mode: Instance creation mode (one of L{constants.INSTANCE_CREATE_MODES})
1248
  @ivar source_handshake: Signed handshake from source (remote import only)
1249
  @ivar source_x509_ca: Source X509 CA in PEM format (remote import only)
1250
  @ivar source_instance_name: Previous name of instance (remote import only)
1251
  @ivar source_shutdown_timeout: Shutdown timeout used for source instance
1252
    (remote import only)
1253

1254
  """
1255
  OP_DSC_FIELD = "instance_name"
1256
  OP_PARAMS = [
1257
    _PInstanceName,
1258
    _PForceVariant,
1259
    _PWaitForSync,
1260
    _PNameCheck,
1261
    _PIgnoreIpolicy,
1262
    _POpportunisticLocking,
1263
    ("beparams", ht.EmptyDict, ht.TDict, "Backend parameters for instance"),
1264
    ("disks", ht.NoDefault, ht.TListOf(_TDiskParams),
1265
     "Disk descriptions, for example ``[{\"%s\": 100}, {\"%s\": 5}]``;"
1266
     " each disk definition must contain a ``%s`` value and"
1267
     " can contain an optional ``%s`` value denoting the disk access mode"
1268
     " (%s)" %
1269
     (constants.IDISK_SIZE, constants.IDISK_SIZE, constants.IDISK_SIZE,
1270
      constants.IDISK_MODE,
1271
      " or ".join("``%s``" % i for i in sorted(constants.DISK_ACCESS_SET)))),
1272
    ("disk_template", ht.NoDefault, _BuildDiskTemplateCheck(True),
1273
     "Disk template"),
1274
    ("file_driver", None, ht.TMaybe(ht.TElemOf(constants.FILE_DRIVER)),
1275
     "Driver for file-backed disks"),
1276
    ("file_storage_dir", None, ht.TMaybeString,
1277
     "Directory for storing file-backed disks"),
1278
    ("hvparams", ht.EmptyDict, ht.TDict,
1279
     "Hypervisor parameters for instance, hypervisor-dependent"),
1280
    ("hypervisor", None, ht.TMaybeString, "Hypervisor"),
1281
    _PIAllocFromDesc("Iallocator for deciding which node(s) to use"),
1282
    ("identify_defaults", False, ht.TBool,
1283
     "Reset instance parameters to default if equal"),
1284
    ("ip_check", True, ht.TBool, _PIpCheckDoc),
1285
    ("conflicts_check", True, ht.TBool, "Check for conflicting IPs"),
1286
    ("mode", ht.NoDefault, ht.TElemOf(constants.INSTANCE_CREATE_MODES),
1287
     "Instance creation mode"),
1288
    ("nics", ht.NoDefault, ht.TListOf(_TestNicDef),
1289
     "List of NIC (network interface) definitions, for example"
1290
     " ``[{}, {}, {\"%s\": \"198.51.100.4\"}]``; each NIC definition can"
1291
     " contain the optional values %s" %
1292
     (constants.INIC_IP,
1293
      ", ".join("``%s``" % i for i in sorted(constants.INIC_PARAMS)))),
1294
    ("no_install", None, ht.TMaybeBool,
1295
     "Do not install the OS (will disable automatic start)"),
1296
    ("osparams", ht.EmptyDict, ht.TDict, "OS parameters for instance"),
1297
    ("os_type", None, ht.TMaybeString, "Operating system"),
1298
    ("pnode", None, ht.TMaybeString, "Primary node"),
1299
    ("snode", None, ht.TMaybeString, "Secondary node"),
1300
    ("source_handshake", None, ht.TMaybe(ht.TList),
1301
     "Signed handshake from source (remote import only)"),
1302
    ("source_instance_name", None, ht.TMaybeString,
1303
     "Source instance name (remote import only)"),
1304
    ("source_shutdown_timeout", constants.DEFAULT_SHUTDOWN_TIMEOUT,
1305
     ht.TNonNegativeInt,
1306
     "How long source instance was given to shut down (remote import only)"),
1307
    ("source_x509_ca", None, ht.TMaybeString,
1308
     "Source X509 CA in PEM format (remote import only)"),
1309
    ("src_node", None, ht.TMaybeString, "Source node for import"),
1310
    ("src_path", None, ht.TMaybeString, "Source directory for import"),
1311
    ("start", True, ht.TBool, "Whether to start instance after creation"),
1312
    ("tags", ht.EmptyList, ht.TListOf(ht.TNonEmptyString), "Instance tags"),
1313
    ]
1314
  OP_RESULT = ht.Comment("instance nodes")(ht.TListOf(ht.TNonEmptyString))
1315

    
1316

    
1317
class OpInstanceMultiAlloc(OpCode):
1318
  """Allocates multiple instances.
1319

1320
  """
1321
  OP_PARAMS = [
1322
    _POpportunisticLocking,
1323
    _PIAllocFromDesc("Iallocator used to allocate all the instances"),
1324
    ("instances", ht.EmptyList, ht.TListOf(ht.TInstanceOf(OpInstanceCreate)),
1325
     "List of instance create opcodes describing the instances to allocate"),
1326
    ]
1327
  _JOB_LIST = ht.Comment("List of submitted jobs")(TJobIdList)
1328
  ALLOCATABLE_KEY = "allocatable"
1329
  FAILED_KEY = "allocatable"
1330
  OP_RESULT = ht.TStrictDict(True, True, {
1331
    constants.JOB_IDS_KEY: _JOB_LIST,
1332
    ALLOCATABLE_KEY: ht.TListOf(ht.TNonEmptyString),
1333
    FAILED_KEY: ht.TListOf(ht.TNonEmptyString),
1334
    })
1335

    
1336
  def __getstate__(self):
1337
    """Generic serializer.
1338

1339
    """
1340
    state = OpCode.__getstate__(self)
1341
    if hasattr(self, "instances"):
1342
      # pylint: disable=E1101
1343
      state["instances"] = [inst.__getstate__() for inst in self.instances]
1344
    return state
1345

    
1346
  def __setstate__(self, state):
1347
    """Generic unserializer.
1348

1349
    This method just restores from the serialized state the attributes
1350
    of the current instance.
1351

1352
    @param state: the serialized opcode data
1353
    @type state: C{dict}
1354

1355
    """
1356
    if not isinstance(state, dict):
1357
      raise ValueError("Invalid data to __setstate__: expected dict, got %s" %
1358
                       type(state))
1359

    
1360
    if "instances" in state:
1361
      state["instances"] = map(OpCode.LoadOpCode, state["instances"])
1362

    
1363
    return OpCode.__setstate__(self, state)
1364

    
1365
  def Validate(self, set_defaults):
1366
    """Validates this opcode.
1367

1368
    We do this recursively.
1369

1370
    """
1371
    OpCode.Validate(self, set_defaults)
1372

    
1373
    for inst in self.instances: # pylint: disable=E1101
1374
      inst.Validate(set_defaults)
1375

    
1376

    
1377
class OpInstanceReinstall(OpCode):
1378
  """Reinstall an instance's OS."""
1379
  OP_DSC_FIELD = "instance_name"
1380
  OP_PARAMS = [
1381
    _PInstanceName,
1382
    _PForceVariant,
1383
    ("os_type", None, ht.TMaybeString, "Instance operating system"),
1384
    ("osparams", None, ht.TMaybeDict, "Temporary OS parameters"),
1385
    ]
1386
  OP_RESULT = ht.TNone
1387

    
1388

    
1389
class OpInstanceRemove(OpCode):
1390
  """Remove an instance."""
1391
  OP_DSC_FIELD = "instance_name"
1392
  OP_PARAMS = [
1393
    _PInstanceName,
1394
    _PShutdownTimeout,
1395
    ("ignore_failures", False, ht.TBool,
1396
     "Whether to ignore failures during removal"),
1397
    ]
1398
  OP_RESULT = ht.TNone
1399

    
1400

    
1401
class OpInstanceRename(OpCode):
1402
  """Rename an instance."""
1403
  OP_PARAMS = [
1404
    _PInstanceName,
1405
    _PNameCheck,
1406
    ("new_name", ht.NoDefault, ht.TNonEmptyString, "New instance name"),
1407
    ("ip_check", False, ht.TBool, _PIpCheckDoc),
1408
    ]
1409
  OP_RESULT = ht.Comment("New instance name")(ht.TNonEmptyString)
1410

    
1411

    
1412
class OpInstanceStartup(OpCode):
1413
  """Startup an instance."""
1414
  OP_DSC_FIELD = "instance_name"
1415
  OP_PARAMS = [
1416
    _PInstanceName,
1417
    _PForce,
1418
    _PIgnoreOfflineNodes,
1419
    ("hvparams", ht.EmptyDict, ht.TDict,
1420
     "Temporary hypervisor parameters, hypervisor-dependent"),
1421
    ("beparams", ht.EmptyDict, ht.TDict, "Temporary backend parameters"),
1422
    _PNoRemember,
1423
    _PStartupPaused,
1424
    ]
1425
  OP_RESULT = ht.TNone
1426

    
1427

    
1428
class OpInstanceShutdown(OpCode):
1429
  """Shutdown an instance."""
1430
  OP_DSC_FIELD = "instance_name"
1431
  OP_PARAMS = [
1432
    _PInstanceName,
1433
    _PIgnoreOfflineNodes,
1434
    ("timeout", constants.DEFAULT_SHUTDOWN_TIMEOUT, ht.TNonNegativeInt,
1435
     "How long to wait for instance to shut down"),
1436
    _PNoRemember,
1437
    ]
1438
  OP_RESULT = ht.TNone
1439

    
1440

    
1441
class OpInstanceReboot(OpCode):
1442
  """Reboot an instance."""
1443
  OP_DSC_FIELD = "instance_name"
1444
  OP_PARAMS = [
1445
    _PInstanceName,
1446
    _PShutdownTimeout,
1447
    ("ignore_secondaries", False, ht.TBool,
1448
     "Whether to start the instance even if secondary disks are failing"),
1449
    ("reboot_type", ht.NoDefault, ht.TElemOf(constants.REBOOT_TYPES),
1450
     "How to reboot instance"),
1451
    ]
1452
  OP_RESULT = ht.TNone
1453

    
1454

    
1455
class OpInstanceReplaceDisks(OpCode):
1456
  """Replace the disks of an instance."""
1457
  OP_DSC_FIELD = "instance_name"
1458
  OP_PARAMS = [
1459
    _PInstanceName,
1460
    _PEarlyRelease,
1461
    _PIgnoreIpolicy,
1462
    ("mode", ht.NoDefault, ht.TElemOf(constants.REPLACE_MODES),
1463
     "Replacement mode"),
1464
    ("disks", ht.EmptyList, ht.TListOf(ht.TNonNegativeInt),
1465
     "Disk indexes"),
1466
    ("remote_node", None, ht.TMaybeString, "New secondary node"),
1467
    _PIAllocFromDesc("Iallocator for deciding new secondary node"),
1468
    ]
1469
  OP_RESULT = ht.TNone
1470

    
1471

    
1472
class OpInstanceFailover(OpCode):
1473
  """Failover an instance."""
1474
  OP_DSC_FIELD = "instance_name"
1475
  OP_PARAMS = [
1476
    _PInstanceName,
1477
    _PShutdownTimeout,
1478
    _PIgnoreConsistency,
1479
    _PMigrationTargetNode,
1480
    _PIgnoreIpolicy,
1481
    _PIAllocFromDesc("Iallocator for deciding the target node for"
1482
                     " shared-storage instances"),
1483
    ]
1484
  OP_RESULT = ht.TNone
1485

    
1486

    
1487
class OpInstanceMigrate(OpCode):
1488
  """Migrate an instance.
1489

1490
  This migrates (without shutting down an instance) to its secondary
1491
  node.
1492

1493
  @ivar instance_name: the name of the instance
1494
  @ivar mode: the migration mode (live, non-live or None for auto)
1495

1496
  """
1497
  OP_DSC_FIELD = "instance_name"
1498
  OP_PARAMS = [
1499
    _PInstanceName,
1500
    _PMigrationMode,
1501
    _PMigrationLive,
1502
    _PMigrationTargetNode,
1503
    _PAllowRuntimeChgs,
1504
    _PIgnoreIpolicy,
1505
    ("cleanup", False, ht.TBool,
1506
     "Whether a previously failed migration should be cleaned up"),
1507
    _PIAllocFromDesc("Iallocator for deciding the target node for"
1508
                     " shared-storage instances"),
1509
    ("allow_failover", False, ht.TBool,
1510
     "Whether we can fallback to failover if migration is not possible"),
1511
    ]
1512
  OP_RESULT = ht.TNone
1513

    
1514

    
1515
class OpInstanceMove(OpCode):
1516
  """Move an instance.
1517

1518
  This move (with shutting down an instance and data copying) to an
1519
  arbitrary node.
1520

1521
  @ivar instance_name: the name of the instance
1522
  @ivar target_node: the destination node
1523

1524
  """
1525
  OP_DSC_FIELD = "instance_name"
1526
  OP_PARAMS = [
1527
    _PInstanceName,
1528
    _PShutdownTimeout,
1529
    _PIgnoreIpolicy,
1530
    ("target_node", ht.NoDefault, ht.TNonEmptyString, "Target node"),
1531
    _PIgnoreConsistency,
1532
    ]
1533
  OP_RESULT = ht.TNone
1534

    
1535

    
1536
class OpInstanceConsole(OpCode):
1537
  """Connect to an instance's console."""
1538
  OP_DSC_FIELD = "instance_name"
1539
  OP_PARAMS = [
1540
    _PInstanceName,
1541
    ]
1542
  OP_RESULT = ht.TDict
1543

    
1544

    
1545
class OpInstanceActivateDisks(OpCode):
1546
  """Activate an instance's disks."""
1547
  OP_DSC_FIELD = "instance_name"
1548
  OP_PARAMS = [
1549
    _PInstanceName,
1550
    ("ignore_size", False, ht.TBool, "Whether to ignore recorded size"),
1551
    _PWaitForSyncFalse,
1552
    ]
1553
  OP_RESULT = ht.TListOf(ht.TAnd(ht.TIsLength(3),
1554
                                 ht.TItems([ht.TNonEmptyString,
1555
                                            ht.TNonEmptyString,
1556
                                            ht.TNonEmptyString])))
1557

    
1558

    
1559
class OpInstanceDeactivateDisks(OpCode):
1560
  """Deactivate an instance's disks."""
1561
  OP_DSC_FIELD = "instance_name"
1562
  OP_PARAMS = [
1563
    _PInstanceName,
1564
    _PForce,
1565
    ]
1566
  OP_RESULT = ht.TNone
1567

    
1568

    
1569
class OpInstanceRecreateDisks(OpCode):
1570
  """Recreate an instance's disks."""
1571
  _TDiskChanges = \
1572
    ht.TAnd(ht.TIsLength(2),
1573
            ht.TItems([ht.Comment("Disk index")(ht.TNonNegativeInt),
1574
                       ht.Comment("Parameters")(_TDiskParams)]))
1575

    
1576
  OP_DSC_FIELD = "instance_name"
1577
  OP_PARAMS = [
1578
    _PInstanceName,
1579
    ("disks", ht.EmptyList,
1580
     ht.TOr(ht.TListOf(ht.TNonNegativeInt), ht.TListOf(_TDiskChanges)),
1581
     "List of disk indexes (deprecated) or a list of tuples containing a disk"
1582
     " index and a possibly empty dictionary with disk parameter changes"),
1583
    ("nodes", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
1584
     "New instance nodes, if relocation is desired"),
1585
    _PIAllocFromDesc("Iallocator for deciding new nodes"),
1586
    ]
1587
  OP_RESULT = ht.TNone
1588

    
1589

    
1590
class OpInstanceQuery(OpCode):
1591
  """Compute the list of instances."""
1592
  OP_PARAMS = [
1593
    _POutputFields,
1594
    _PUseLocking,
1595
    ("names", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
1596
     "Empty list to query all instances, instance names otherwise"),
1597
    ]
1598
  OP_RESULT = _TOldQueryResult
1599

    
1600

    
1601
class OpInstanceQueryData(OpCode):
1602
  """Compute the run-time status of instances."""
1603
  OP_PARAMS = [
1604
    _PUseLocking,
1605
    ("instances", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
1606
     "Instance names"),
1607
    ("static", False, ht.TBool,
1608
     "Whether to only return configuration data without querying"
1609
     " nodes"),
1610
    ]
1611
  OP_RESULT = ht.TDictOf(ht.TNonEmptyString, ht.TDict)
1612

    
1613

    
1614
def _TestInstSetParamsModList(fn):
1615
  """Generates a check for modification lists.
1616

1617
  """
1618
  # Old format
1619
  # TODO: Remove in version 2.8 including support in LUInstanceSetParams
1620
  old_mod_item_fn = \
1621
    ht.TAnd(ht.TIsLength(2), ht.TItems([
1622
      ht.TOr(ht.TElemOf(constants.DDMS_VALUES), ht.TNonNegativeInt),
1623
      fn,
1624
      ]))
1625

    
1626
  # New format, supporting adding/removing disks/NICs at arbitrary indices
1627
  mod_item_fn = \
1628
    ht.TAnd(ht.TIsLength(3), ht.TItems([
1629
      ht.TElemOf(constants.DDMS_VALUES_WITH_MODIFY),
1630
      ht.Comment("Disk index, can be negative, e.g. -1 for last disk")(ht.TInt),
1631
      fn,
1632
      ]))
1633

    
1634
  return ht.TOr(ht.Comment("Recommended")(ht.TListOf(mod_item_fn)),
1635
                ht.Comment("Deprecated")(ht.TListOf(old_mod_item_fn)))
1636

    
1637

    
1638
class OpInstanceSetParams(OpCode):
1639
  """Change the parameters of an instance.
1640

1641
  """
1642
  TestNicModifications = _TestInstSetParamsModList(_TestNicDef)
1643
  TestDiskModifications = _TestInstSetParamsModList(_TDiskParams)
1644

    
1645
  OP_DSC_FIELD = "instance_name"
1646
  OP_PARAMS = [
1647
    _PInstanceName,
1648
    _PForce,
1649
    _PForceVariant,
1650
    _PIgnoreIpolicy,
1651
    ("nics", ht.EmptyList, TestNicModifications,
1652
     "List of NIC changes: each item is of the form ``(op, index, settings)``,"
1653
     " ``op`` is one of ``%s``, ``%s`` or ``%s``, ``index`` can be either -1"
1654
     " to refer to the last position, or a zero-based index number; a"
1655
     " deprecated version of this parameter used the form ``(op, settings)``,"
1656
     " where ``op`` can be ``%s`` to add a new NIC with the specified"
1657
     " settings, ``%s`` to remove the last NIC or a number to modify the"
1658
     " settings of the NIC with that index" %
1659
     (constants.DDM_ADD, constants.DDM_MODIFY, constants.DDM_REMOVE,
1660
      constants.DDM_ADD, constants.DDM_REMOVE)),
1661
    ("disks", ht.EmptyList, TestDiskModifications,
1662
     "List of disk changes; see ``nics``"),
1663
    ("beparams", ht.EmptyDict, ht.TDict, "Per-instance backend parameters"),
1664
    ("runtime_mem", None, ht.TMaybePositiveInt, "New runtime memory"),
1665
    ("hvparams", ht.EmptyDict, ht.TDict,
1666
     "Per-instance hypervisor parameters, hypervisor-dependent"),
1667
    ("disk_template", None, ht.TMaybe(_BuildDiskTemplateCheck(False)),
1668
     "Disk template for instance"),
1669
    ("remote_node", None, ht.TMaybeString,
1670
     "Secondary node (used when changing disk template)"),
1671
    ("os_name", None, ht.TMaybeString,
1672
     "Change the instance's OS without reinstalling the instance"),
1673
    ("osparams", None, ht.TMaybeDict, "Per-instance OS parameters"),
1674
    ("wait_for_sync", True, ht.TBool,
1675
     "Whether to wait for the disk to synchronize, when changing template"),
1676
    ("offline", None, ht.TMaybeBool, "Whether to mark instance as offline"),
1677
    ("conflicts_check", True, ht.TBool, "Check for conflicting IPs"),
1678
    ]
1679
  OP_RESULT = _TSetParamsResult
1680

    
1681

    
1682
class OpInstanceGrowDisk(OpCode):
1683
  """Grow a disk of an instance."""
1684
  OP_DSC_FIELD = "instance_name"
1685
  OP_PARAMS = [
1686
    _PInstanceName,
1687
    _PWaitForSync,
1688
    ("disk", ht.NoDefault, ht.TInt, "Disk index"),
1689
    ("amount", ht.NoDefault, ht.TNonNegativeInt,
1690
     "Amount of disk space to add (megabytes)"),
1691
    ("absolute", False, ht.TBool,
1692
     "Whether the amount parameter is an absolute target or a relative one"),
1693
    ]
1694
  OP_RESULT = ht.TNone
1695

    
1696

    
1697
class OpInstanceChangeGroup(OpCode):
1698
  """Moves an instance to another node group."""
1699
  OP_DSC_FIELD = "instance_name"
1700
  OP_PARAMS = [
1701
    _PInstanceName,
1702
    _PEarlyRelease,
1703
    _PIAllocFromDesc("Iallocator for computing solution"),
1704
    ("target_groups", None, ht.TMaybeListOf(ht.TNonEmptyString),
1705
     "Destination group names or UUIDs (defaults to \"all but current group\""),
1706
    ]
1707
  OP_RESULT = TJobIdListOnly
1708

    
1709

    
1710
# Node group opcodes
1711

    
1712
class OpGroupAdd(OpCode):
1713
  """Add a node group to the cluster."""
1714
  OP_DSC_FIELD = "group_name"
1715
  OP_PARAMS = [
1716
    _PGroupName,
1717
    _PNodeGroupAllocPolicy,
1718
    _PGroupNodeParams,
1719
    _PDiskParams,
1720
    _PHvState,
1721
    _PDiskState,
1722
    ("ipolicy", None, ht.TMaybeDict,
1723
     "Group-wide :ref:`instance policy <rapi-ipolicy>` specs"),
1724
    ]
1725
  OP_RESULT = ht.TNone
1726

    
1727

    
1728
class OpGroupAssignNodes(OpCode):
1729
  """Assign nodes to a node group."""
1730
  OP_DSC_FIELD = "group_name"
1731
  OP_PARAMS = [
1732
    _PGroupName,
1733
    _PForce,
1734
    ("nodes", ht.NoDefault, ht.TListOf(ht.TNonEmptyString),
1735
     "List of nodes to assign"),
1736
    ]
1737
  OP_RESULT = ht.TNone
1738

    
1739

    
1740
class OpGroupQuery(OpCode):
1741
  """Compute the list of node groups."""
1742
  OP_PARAMS = [
1743
    _POutputFields,
1744
    ("names", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
1745
     "Empty list to query all groups, group names otherwise"),
1746
    ]
1747
  OP_RESULT = _TOldQueryResult
1748

    
1749

    
1750
class OpGroupSetParams(OpCode):
1751
  """Change the parameters of a node group."""
1752
  OP_DSC_FIELD = "group_name"
1753
  OP_PARAMS = [
1754
    _PGroupName,
1755
    _PNodeGroupAllocPolicy,
1756
    _PGroupNodeParams,
1757
    _PDiskParams,
1758
    _PHvState,
1759
    _PDiskState,
1760
    ("ipolicy", None, ht.TMaybeDict, "Group-wide instance policy specs"),
1761
    ]
1762
  OP_RESULT = _TSetParamsResult
1763

    
1764

    
1765
class OpGroupRemove(OpCode):
1766
  """Remove a node group from the cluster."""
1767
  OP_DSC_FIELD = "group_name"
1768
  OP_PARAMS = [
1769
    _PGroupName,
1770
    ]
1771
  OP_RESULT = ht.TNone
1772

    
1773

    
1774
class OpGroupRename(OpCode):
1775
  """Rename a node group in the cluster."""
1776
  OP_PARAMS = [
1777
    _PGroupName,
1778
    ("new_name", ht.NoDefault, ht.TNonEmptyString, "New group name"),
1779
    ]
1780
  OP_RESULT = ht.Comment("New group name")(ht.TNonEmptyString)
1781

    
1782

    
1783
class OpGroupEvacuate(OpCode):
1784
  """Evacuate a node group in the cluster."""
1785
  OP_DSC_FIELD = "group_name"
1786
  OP_PARAMS = [
1787
    _PGroupName,
1788
    _PEarlyRelease,
1789
    _PIAllocFromDesc("Iallocator for computing solution"),
1790
    ("target_groups", None, ht.TMaybeListOf(ht.TNonEmptyString),
1791
     "Destination group names or UUIDs"),
1792
    ]
1793
  OP_RESULT = TJobIdListOnly
1794

    
1795

    
1796
# OS opcodes
1797
class OpOsDiagnose(OpCode):
1798
  """Compute the list of guest operating systems."""
1799
  OP_PARAMS = [
1800
    _POutputFields,
1801
    ("names", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
1802
     "Which operating systems to diagnose"),
1803
    ]
1804
  OP_RESULT = _TOldQueryResult
1805

    
1806

    
1807
# Exports opcodes
1808
class OpBackupQuery(OpCode):
1809
  """Compute the list of exported images."""
1810
  OP_PARAMS = [
1811
    _PUseLocking,
1812
    ("nodes", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
1813
     "Empty list to query all nodes, node names otherwise"),
1814
    ]
1815
  OP_RESULT = ht.TDictOf(ht.TNonEmptyString,
1816
                         ht.TOr(ht.Comment("False on error")(ht.TBool),
1817
                                ht.TListOf(ht.TNonEmptyString)))
1818

    
1819

    
1820
class OpBackupPrepare(OpCode):
1821
  """Prepares an instance export.
1822

1823
  @ivar instance_name: Instance name
1824
  @ivar mode: Export mode (one of L{constants.EXPORT_MODES})
1825

1826
  """
1827
  OP_DSC_FIELD = "instance_name"
1828
  OP_PARAMS = [
1829
    _PInstanceName,
1830
    ("mode", ht.NoDefault, ht.TElemOf(constants.EXPORT_MODES),
1831
     "Export mode"),
1832
    ]
1833
  OP_RESULT = ht.TMaybeDict
1834

    
1835

    
1836
class OpBackupExport(OpCode):
1837
  """Export an instance.
1838

1839
  For local exports, the export destination is the node name. For
1840
  remote exports, the export destination is a list of tuples, each
1841
  consisting of hostname/IP address, port, magic, HMAC and HMAC
1842
  salt. The HMAC is calculated using the cluster domain secret over
1843
  the value "${index}:${hostname}:${port}". The destination X509 CA
1844
  must be a signed certificate.
1845

1846
  @ivar mode: Export mode (one of L{constants.EXPORT_MODES})
1847
  @ivar target_node: Export destination
1848
  @ivar x509_key_name: X509 key to use (remote export only)
1849
  @ivar destination_x509_ca: Destination X509 CA in PEM format (remote export
1850
                             only)
1851

1852
  """
1853
  OP_DSC_FIELD = "instance_name"
1854
  OP_PARAMS = [
1855
    _PInstanceName,
1856
    _PShutdownTimeout,
1857
    # TODO: Rename target_node as it changes meaning for different export modes
1858
    # (e.g. "destination")
1859
    ("target_node", ht.NoDefault, ht.TOr(ht.TNonEmptyString, ht.TList),
1860
     "Destination information, depends on export mode"),
1861
    ("shutdown", True, ht.TBool, "Whether to shutdown instance before export"),
1862
    ("remove_instance", False, ht.TBool,
1863
     "Whether to remove instance after export"),
1864
    ("ignore_remove_failures", False, ht.TBool,
1865
     "Whether to ignore failures while removing instances"),
1866
    ("mode", constants.EXPORT_MODE_LOCAL, ht.TElemOf(constants.EXPORT_MODES),
1867
     "Export mode"),
1868
    ("x509_key_name", None, ht.TMaybe(ht.TList),
1869
     "Name of X509 key (remote export only)"),
1870
    ("destination_x509_ca", None, ht.TMaybeString,
1871
     "Destination X509 CA (remote export only)"),
1872
    ]
1873
  OP_RESULT = \
1874
    ht.TAnd(ht.TIsLength(2), ht.TItems([
1875
      ht.Comment("Finalizing status")(ht.TBool),
1876
      ht.Comment("Status for every exported disk")(ht.TListOf(ht.TBool)),
1877
      ]))
1878

    
1879

    
1880
class OpBackupRemove(OpCode):
1881
  """Remove an instance's export."""
1882
  OP_DSC_FIELD = "instance_name"
1883
  OP_PARAMS = [
1884
    _PInstanceName,
1885
    ]
1886
  OP_RESULT = ht.TNone
1887

    
1888

    
1889
# Tags opcodes
1890
class OpTagsGet(OpCode):
1891
  """Returns the tags of the given object."""
1892
  OP_DSC_FIELD = "name"
1893
  OP_PARAMS = [
1894
    _PTagKind,
1895
    # Not using _PUseLocking as the default is different for historical reasons
1896
    ("use_locking", True, ht.TBool, "Whether to use synchronization"),
1897
    # Name is only meaningful for nodes and instances
1898
    ("name", ht.NoDefault, ht.TMaybeString,
1899
     "Name of object to retrieve tags from"),
1900
    ]
1901
  OP_RESULT = ht.TListOf(ht.TNonEmptyString)
1902

    
1903

    
1904
class OpTagsSearch(OpCode):
1905
  """Searches the tags in the cluster for a given pattern."""
1906
  OP_DSC_FIELD = "pattern"
1907
  OP_PARAMS = [
1908
    ("pattern", ht.NoDefault, ht.TNonEmptyString,
1909
     "Search pattern (regular expression)"),
1910
    ]
1911
  OP_RESULT = ht.TListOf(ht.TAnd(ht.TIsLength(2), ht.TItems([
1912
    ht.TNonEmptyString,
1913
    ht.TNonEmptyString,
1914
    ])))
1915

    
1916

    
1917
class OpTagsSet(OpCode):
1918
  """Add a list of tags on a given object."""
1919
  OP_PARAMS = [
1920
    _PTagKind,
1921
    _PTags,
1922
    # Name is only meaningful for groups, nodes and instances
1923
    ("name", ht.NoDefault, ht.TMaybeString,
1924
     "Name of object where tag(s) should be added"),
1925
    ]
1926
  OP_RESULT = ht.TNone
1927

    
1928

    
1929
class OpTagsDel(OpCode):
1930
  """Remove a list of tags from a given object."""
1931
  OP_PARAMS = [
1932
    _PTagKind,
1933
    _PTags,
1934
    # Name is only meaningful for groups, nodes and instances
1935
    ("name", ht.NoDefault, ht.TMaybeString,
1936
     "Name of object where tag(s) should be deleted"),
1937
    ]
1938
  OP_RESULT = ht.TNone
1939

    
1940

    
1941
# Test opcodes
1942
class OpTestDelay(OpCode):
1943
  """Sleeps for a configured amount of time.
1944

1945
  This is used just for debugging and testing.
1946

1947
  Parameters:
1948
    - duration: the time to sleep
1949
    - on_master: if true, sleep on the master
1950
    - on_nodes: list of nodes in which to sleep
1951

1952
  If the on_master parameter is true, it will execute a sleep on the
1953
  master (before any node sleep).
1954

1955
  If the on_nodes list is not empty, it will sleep on those nodes
1956
  (after the sleep on the master, if that is enabled).
1957

1958
  As an additional feature, the case of duration < 0 will be reported
1959
  as an execution error, so this opcode can be used as a failure
1960
  generator. The case of duration == 0 will not be treated specially.
1961

1962
  """
1963
  OP_DSC_FIELD = "duration"
1964
  OP_PARAMS = [
1965
    ("duration", ht.NoDefault, ht.TNumber, None),
1966
    ("on_master", True, ht.TBool, None),
1967
    ("on_nodes", ht.EmptyList, ht.TListOf(ht.TNonEmptyString), None),
1968
    ("repeat", 0, ht.TNonNegativeInt, None),
1969
    ]
1970

    
1971
  def OP_DSC_FORMATTER(self, value): # pylint: disable=C0103,R0201
1972
    """Custom formatter for duration.
1973

1974
    """
1975
    try:
1976
      v = float(value)
1977
    except TypeError:
1978
      v = value
1979
    return str(v)
1980

    
1981

    
1982
class OpTestAllocator(OpCode):
1983
  """Allocator framework testing.
1984

1985
  This opcode has two modes:
1986
    - gather and return allocator input for a given mode (allocate new
1987
      or replace secondary) and a given instance definition (direction
1988
      'in')
1989
    - run a selected allocator for a given operation (as above) and
1990
      return the allocator output (direction 'out')
1991

1992
  """
1993
  OP_DSC_FIELD = "iallocator"
1994
  OP_PARAMS = [
1995
    ("direction", ht.NoDefault,
1996
     ht.TElemOf(constants.VALID_IALLOCATOR_DIRECTIONS), None),
1997
    ("mode", ht.NoDefault, ht.TElemOf(constants.VALID_IALLOCATOR_MODES), None),
1998
    ("name", ht.NoDefault, ht.TNonEmptyString, None),
1999
    ("nics", ht.NoDefault,
2000
     ht.TMaybeListOf(ht.TDictOf(ht.TElemOf([constants.INIC_MAC,
2001
                                            constants.INIC_IP,
2002
                                            "bridge"]),
2003
                                ht.TMaybeString)),
2004
     None),
2005
    ("disks", ht.NoDefault, ht.TMaybe(ht.TList), None),
2006
    ("hypervisor", None, ht.TMaybeString, None),
2007
    _PIAllocFromDesc(None),
2008
    ("tags", ht.EmptyList, ht.TListOf(ht.TNonEmptyString), None),
2009
    ("memory", None, ht.TMaybe(ht.TNonNegativeInt), None),
2010
    ("vcpus", None, ht.TMaybe(ht.TNonNegativeInt), None),
2011
    ("os", None, ht.TMaybeString, None),
2012
    ("disk_template", None, ht.TMaybeString, None),
2013
    ("instances", None, ht.TMaybeListOf(ht.TNonEmptyString), None),
2014
    ("evac_mode", None,
2015
     ht.TMaybe(ht.TElemOf(constants.IALLOCATOR_NEVAC_MODES)), None),
2016
    ("target_groups", None, ht.TMaybeListOf(ht.TNonEmptyString), None),
2017
    ("spindle_use", 1, ht.TNonNegativeInt, None),
2018
    ("count", 1, ht.TNonNegativeInt, None),
2019
    ]
2020

    
2021

    
2022
class OpTestJqueue(OpCode):
2023
  """Utility opcode to test some aspects of the job queue.
2024

2025
  """
2026
  OP_PARAMS = [
2027
    ("notify_waitlock", False, ht.TBool, None),
2028
    ("notify_exec", False, ht.TBool, None),
2029
    ("log_messages", ht.EmptyList, ht.TListOf(ht.TString), None),
2030
    ("fail", False, ht.TBool, None),
2031
    ]
2032

    
2033

    
2034
class OpTestDummy(OpCode):
2035
  """Utility opcode used by unittests.
2036

2037
  """
2038
  OP_PARAMS = [
2039
    ("result", ht.NoDefault, ht.NoType, None),
2040
    ("messages", ht.NoDefault, ht.NoType, None),
2041
    ("fail", ht.NoDefault, ht.NoType, None),
2042
    ("submit_jobs", None, ht.NoType, None),
2043
    ]
2044
  WITH_LU = False
2045

    
2046

    
2047
# Network opcodes
2048
# Add a new network in the cluster
2049
class OpNetworkAdd(OpCode):
2050
  """Add an IP network to the cluster."""
2051
  OP_DSC_FIELD = "network_name"
2052
  OP_PARAMS = [
2053
    _PNetworkName,
2054
    ("network_type", None, ht.TMaybe(_CheckNetworkType), "Network type"),
2055
    ("network", ht.NoDefault, _TIpNetwork4, "IPv4 subnet"),
2056
    ("gateway", None, ht.TMaybe(_TIpAddress4), "IPv4 gateway"),
2057
    ("network6", None, ht.TMaybe(_TIpNetwork6), "IPv6 subnet"),
2058
    ("gateway6", None, ht.TMaybe(_TIpAddress6), "IPv6 gateway"),
2059
    ("mac_prefix", None, ht.TMaybeString,
2060
     "MAC address prefix that overrides cluster one"),
2061
    ("add_reserved_ips", None, _TMaybeAddr4List,
2062
     "Which IP addresses to reserve"),
2063
    ("conflicts_check", True, ht.TBool,
2064
     "Whether to check for conflicting IP addresses"),
2065
    ("tags", ht.EmptyList, ht.TListOf(ht.TNonEmptyString), "Network tags"),
2066
    ]
2067
  OP_RESULT = ht.TNone
2068

    
2069

    
2070
class OpNetworkRemove(OpCode):
2071
  """Remove an existing network from the cluster.
2072
     Must not be connected to any nodegroup.
2073

2074
  """
2075
  OP_DSC_FIELD = "network_name"
2076
  OP_PARAMS = [
2077
    _PNetworkName,
2078
    _PForce,
2079
    ]
2080
  OP_RESULT = ht.TNone
2081

    
2082

    
2083
class OpNetworkSetParams(OpCode):
2084
  """Modify Network's parameters except for IPv4 subnet"""
2085
  OP_DSC_FIELD = "network_name"
2086
  OP_PARAMS = [
2087
    _PNetworkName,
2088
    ("network_type", None, ht.TMaybeValueNone(_CheckNetworkType),
2089
     "Network type"),
2090
    ("gateway", None, ht.TMaybeValueNone(_TIpAddress4), "IPv4 gateway"),
2091
    ("network6", None, ht.TMaybeValueNone(_TIpNetwork6), "IPv6 subnet"),
2092
    ("gateway6", None, ht.TMaybeValueNone(_TIpAddress6), "IPv6 gateway"),
2093
    ("mac_prefix", None, ht.TMaybeValueNone(ht.TString),
2094
     "MAC address prefix that overrides cluster one"),
2095
    ("add_reserved_ips", None, _TMaybeAddr4List,
2096
     "Which external IP addresses to reserve"),
2097
    ("remove_reserved_ips", None, _TMaybeAddr4List,
2098
     "Which external IP addresses to release"),
2099
    ]
2100
  OP_RESULT = ht.TNone
2101

    
2102

    
2103
class OpNetworkConnect(OpCode):
2104
  """Connect a Network to a specific Nodegroup with the defined netparams
2105
     (mode, link). Nics in this Network will inherit those params.
2106
     Produce errors if a NIC (that its not already assigned to a network)
2107
     has an IP that is contained in the Network this will produce error unless
2108
     --no-conflicts-check is passed.
2109

2110
  """
2111
  OP_DSC_FIELD = "network_name"
2112
  OP_PARAMS = [
2113
    _PGroupName,
2114
    _PNetworkName,
2115
    ("network_mode", ht.NoDefault, ht.TString, "Connectivity mode"),
2116
    ("network_link", ht.NoDefault, ht.TString, "Connectivity link"),
2117
    ("conflicts_check", True, ht.TBool, "Whether to check for conflicting IPs"),
2118
    ]
2119
  OP_RESULT = ht.TNone
2120

    
2121

    
2122
class OpNetworkDisconnect(OpCode):
2123
  """Disconnect a Network from a Nodegroup. Produce errors if NICs are
2124
     present in the Network unless --no-conficts-check option is passed.
2125

2126
  """
2127
  OP_DSC_FIELD = "network_name"
2128
  OP_PARAMS = [
2129
    _PGroupName,
2130
    _PNetworkName,
2131
    ("conflicts_check", True, ht.TBool, "Whether to check for conflicting IPs"),
2132
    ]
2133
  OP_RESULT = ht.TNone
2134

    
2135

    
2136
class OpNetworkQuery(OpCode):
2137
  """Compute the list of networks."""
2138
  OP_PARAMS = [
2139
    _POutputFields,
2140
    ("names", ht.EmptyList, ht.TListOf(ht.TNonEmptyString),
2141
     "Empty list to query all groups, group names otherwise"),
2142
    ]
2143
  OP_RESULT = _TOldQueryResult
2144

    
2145

    
2146
def _GetOpList():
2147
  """Returns list of all defined opcodes.
2148

2149
  Does not eliminate duplicates by C{OP_ID}.
2150

2151
  """
2152
  return [v for v in globals().values()
2153
          if (isinstance(v, type) and issubclass(v, OpCode) and
2154
              hasattr(v, "OP_ID") and v is not OpCode)]
2155

    
2156

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