Class: Fog::Hyperv::Compute::Server

Inherits:
Compute::Server
  • Object
show all
Extended by:
ModelExtends
Includes:
ModelIncludes
Defined in:
lib/fog/hyperv/compute/models/server.rb

Overview

A Hyper-V VM

Constant Summary collapse

VM_STATE_ENUM_VALUES =
Note:

Defined by Microsoft.HyperV.PowerShell.VMState

VM runtime state

{
  Other:              1,
  Running:            2,
  Off:                3,
  Stopping:           4,
  Saved:              6,
  Paused:             9,
  Starting:           10,
  Reset:              11,
  Saving:             32_773,
  Pausing:            32_776,
  Resuming:           32_777,
  FastSaved:          32_779,
  FastSaving:         32_780,
  ForceShutdown:      32_781,
  ForceReboot:        32_782,
  Hibernated:         32_783,
  ComponentServicing: 32_784,
  RunningCritical:    32_785,
  OffCritical:        32_786,
  StoppingCritical:   32_787,
  SavedCritical:      32_788,
  PausedCritical:     32_789,
  StartingCritical:   32_790,
  ResetCritical:      32_791,
  SavingCritical:     32_792,
  PausingCritical:    32_793,
  ResumingCritical:   32_794,
  FastSavedCritical:  32_795,
  FastSavingCritical: 32_796
}.freeze
VM_STATUS_ENUM_VALUES =
Note:

Defined by Microsoft.HyperV.PowerShell.VMOperationalStatus

VM object status

{
  Ok:                        2,
  Degraded:                  3,
  PredictiveFailure:         5,
  InService:                 11,
  Dormant:                   15,
  SupportingEntityInError:   16,
  CreatingSnapshot:          32_768,
  ApplyingSnapshot:          23_769,
  DeletingSnapshot:          32_770,
  WaitingToStart:            32_771,
  MergingDisks:              32_772,
  ExportingVirtualMachine:   32_773,
  MigratingVirtualMachine:   32_774,
  BackingUpVirtualMachine:   32_776,
  ModifyingUpVirtualMachine: 32_777,
  StorageMigrationPhaseOne:  32_778,
  StorageMigrationPhaseTwo:  32_779,
  MigratingPlannedVm:        32_780,
  CheckingCompatibility:     32_781,
  ApplicationCriticalState:  32_782,
  CommunicationTimedOut:     32_783,
  CommunicationFailed:       32_784,
  NoIommu:                   32_785,
  NoIovSupportInNic:         32_786,
  SwitchNotInIovMode:        32_787,
  IovBlockedByPolicy:        32_788,
  IovNoAvailResources:       32_789,
  IovGuestDriversNeeded:     32_790,
  CriticalIoError:           32_795
}.freeze
VM_GENERATION_VALUES =

VM firmware generation - i.e. BIOS/UEFI

{
  BIOS: 1,
  UEFI: 2
}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from ModelExtends

collection

Methods included from ModelIncludes

#cluster, #computer, #dirty, #dirty?, #vm

Constructor Details

#initialize(attrs = {}) ⇒ Server

Returns a new instance of Server.



180
181
182
183
184
185
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 180

def initialize(attrs = {})
  @cluster = attrs.delete :cluster
  @computer = attrs.delete :computer

  super
end

Instance Attribute Details

#bios ⇒ Bios, Firmware (readonly) Also known as: firmware

Returns BIOS/UEFI configuration depending on generation.

Returns:

  • (Bios, Firmware) —

    BIOS/UEFI configuration depending on generation



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 189

def bios
  associations[:bios] ||= begin
    requires :generation, :id
    if generation == :BIOS
      klass = Fog::Hyperv::Compute::Bios
      method = :get_vm_bios
    else
      klass = Fog::Hyperv::Compute::Firmware
      method = :get_vm_firmware
    end

    klass.new(
      **service.public_send(
        method,
        computer_name: computer_name,
        vm_id: vm_id,

        _return_fields: klass.attributes
      ),

      vm: self,
      service: @service,
      computer: @computer,
      cluster: @cluster
    )
  end
end

#com_ports ⇒ Array<ComPort>

Returns the COM ports on the VM.

Returns:

  • (Array<ComPort>) —

    the COM ports on the VM



156
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 156

collection :com_ports

#computer_name ⇒ String (readonly)

Returns the name of the host running the VM.

Returns:

  • (String) —

    the name of the host running the VM



99
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 99

attribute :computer_name

#creation_time ⇒ Time (readonly)

Returns the time the VM was created.

Returns:

  • (Time) —

    the time the VM was created



107
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 107

attribute :creation_time, type: :hypervdatetime

#dvd_drives ⇒ Array<DvdDrive>

Returns the DVD drives on the VM.

Returns:

  • (Array<DvdDrive>) —

    the DVD drives on the VM



159
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 159

collection :dvd_drives

#dynamic_memory_enabled ⇒ Boolean

Returns if memory is dynamically handled - sliding between #memory_minimum and #memory_maximum.

Returns:

  • (Boolean) —

    if memory is dynamically handled - sliding between #memory_minimum and #memory_maximum



110
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 110

attribute :dynamic_memory_enabled, type: :boolean, default: false

#floppy_drives ⇒ Array<FloppyDrive>

Note:

only supported on #generation :BIOS

Returns the floppy drives on the VM.

Returns:



163
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 163

collection :floppy_drives

#generation ⇒ Symbol (readonly)

Returns the VM firmware generation.

Returns:

  • (Symbol) —

    the VM firmware generation



113
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 113

attribute :generation, type: :hypervenum, values: VM_GENERATION_VALUES, default: :UEFI

#hard_drives ⇒ Array<HardDrive>

Returns the hard drives on the VM.

Returns:

  • (Array<HardDrive>) —

    the hard drives on the VM



166
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 166

collection :hard_drives

#id ⇒ String (readonly) Also known as: vm_id

Returns the GUID of the VM.

Returns:

  • (String) —

    the GUID of the VM



94
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 94

identity :id

#integration_services ⇒ Array<IntegrationService>

Returns the integration services on the VM.

Returns:



169
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 169

collection :integration_services

#is_clustered ⇒ Boolean (readonly)

Returns iv the VM is clustered.

Returns:

  • (Boolean) —

    iv the VM is clustered



116
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 116

attribute :is_clustered, type: :boolean, default: false

#memory_assigned ⇒ Integer (readonly)

Returns the memory assigned to the VM on startup.

Returns:

  • (Integer) —

    the memory assigned to the VM on startup



131
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 131

attribute :memory_assigned, type: :integer

#memory_maximum ⇒ Integer

Returns the maximum amount of memory the VM can assign when #dynamic_memory_enabled.

Returns:

  • (Integer) —

    the maximum amount of memory the VM can assign when #dynamic_memory_enabled



134
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 134

attribute :memory_maximum, type: :integer, default: 17_179_869_184

#memory_minimum ⇒ Integer

Returns the minimum amount of memory the VM can assign when #dynamic_memory_enabled.

Returns:

  • (Integer) —

    the minimum amount of memory the VM can assign when #dynamic_memory_enabled



137
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 137

attribute :memory_minimum, type: :integer, default: 536_870_912

#memory_startup ⇒ Integer

Returns the starting amount of memory the VM will be assigned.

Returns:

  • (Integer) —

    the starting amount of memory the VM will be assigned



140
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 140

attribute :memory_startup, type: :integer, default: 536_870_912

#name ⇒ String Also known as: vm_name

Returns the name of the VM.

Returns:

  • (String) —

    the name of the VM



103
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 103

attribute :name

#network_adapters ⇒ Array<NetworkAdapter>

Returns the network adapters on the VM.

Returns:



172
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 172

collection :network_adapters

#notes ⇒ String

Returns user-specified notes for the VM.

Returns:

  • (String) —

    user-specified notes for the VM



143
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 143

attribute :notes, type: :string

#path ⇒ String

Returns the path on disk where the VM configuration is stored.

Returns:

  • (String) —

    the path on disk where the VM configuration is stored



146
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 146

attribute :path, type: :string

#primary_operational_status ⇒ Symbol (readonly)

Returns the primary status of the VM.

Returns:

  • (Symbol) —

    the primary status of the VM

See Also:



124
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 124

attribute :primary_operational_status, type: :hypervenum, values: VM_STATUS_ENUM_VALUES

#processor_count ⇒ Integer

Returns the number of processors in the VM.

Returns:

  • (Integer) —

    the number of processors in the VM



149
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 149

attribute :processor_count, type: :integer, default: 1

#secondary_operational_status ⇒ Symbol (readonly)

Returns the secondary status of the VM.

Returns:

  • (Symbol) —

    the secondary status of the VM

See Also:



128
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 128

attribute :secondary_operational_status, type: :hypervenum, values: VM_STATUS_ENUM_VALUES

#security ⇒ Security (readonly)

Returns UEFI security configuration, if #generation is :UEFI.

Returns:

  • (Security) —

    UEFI security configuration, if #generation is :UEFI



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 220

def security
  return unless persisted?

  requires :generation
  return unless generation == :UEFI

  security = service.get_vm_security(
    computer_name: computer_name,
    vm_id: vm_id,

    _return_fields: Fog::Hyperv::Compute::Security.attributes
  )
  return unless security.is_a? Hash

  associations[:security] ||= Fog::Hyperv::Compute::Security.new(
    **security,

    vm: self,
    service: @service,
    computer: @computer,
    cluster: @cluster
  )
end

#state ⇒ Symbol (readonly)

Returns the state of the VM.

Returns:

  • (Symbol) —

    the state of the VM

See Also:



120
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 120

attribute :state, type: :hypervenum, values: VM_STATE_ENUM_VALUES

#tpm_enabled ⇒ Boolean

Returns if a vTPM is enabled on the VM, only available if #generation is :UEFI.

Returns:

  • (Boolean) —

    if a vTPM is enabled on the VM, only available if #generation is :UEFI



246
247
248
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 246

def tpm_enabled
  security&.tpm_enabled
end

#uptime ⇒ Time (readonly)

Returns the amount of time the VM has been online.

Returns:

  • (Time) —

    the amount of time the VM has been online



152
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 152

attribute :uptime, type: :hypervtimespan

#vhds ⇒ Array<Vhd>

Returns the VHD images in use by the VM.

Returns:

  • (Array<Vhd>) —

    the VHD images in use by the VM



175
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 175

collection :vhds

Instance Method Details

#build_config_path(subdir = nil) ⇒ String

Build a path for where to store configuration files

Returns:

  • (String) —

    the absolute path for the configuration store



454
455
456
457
458
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 454

def build_config_path(subdir = nil)
  requires :name

  [computer.virtual_machine_path, name, subdir].compact.join('\\')
end

#build_vhd_path(filename = nil) ⇒ String

Build a path for where to store a VHD of a given name

Returns:

  • (String) —

    the absolute path for the VHD



446
447
448
449
450
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 446

def build_vhd_path(filename = nil)
  requires :name

  [computer.virtual_hard_disk_path, name, filename].compact.join('\\')
end

#create(boot_device: nil, switch_name: nil, **attrs) ⇒ Object

Create the VM object if it doesn’t exist

Parameters:

  • boot_device (Symbol) (defaults to: nil) —

    the default boot device to configure the VM with, one of BOOT_DEVICE

  • switch_name (String) (defaults to: nil) —

    the name of a Switch to connect the VM to on creation

  • attrs (Hash) —

    a customizable set of options

Options Hash (**attrs):

  • :path (String) —

    a custom path to store the VM configuration under - will use a subdir under the default config path if relative



340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 340

def create(boot_device: nil, switch_name: nil, **attrs)
  attrs[:no_vhd] = true unless attrs[:new_vhd_path]
  attrs[:path] = [computer.virtual_machine_path, attrs[:path]].join('\\') \
    if attrs[:path] && attrs[:path] !~ %r{^(\w:[\\/]|[\\/]{2}\w+[\\/])}i

  # Attributes that can't be set as part of the New-VM call
  post_create_attributes = {
    processor_count: processor_count > 1 ? processor_count : nil,
    notes: notes.nil? || notes == '' ? nil : notes
  }
  if dynamic_memory_enabled
    post_create_attributes.merge!(
      dynamic_memory_enabled: true,
      memory_minimum_bytes: memory_minimum,
      memory_maximum_bytes: memory_maximum
    )
  end
  post_create_attributes.compact!

  merge_attributes(
    service.new_vm(
      computer_name: computer_name,
      name: name,

      generation: generation_num,
      memory_startup_bytes: memory_startup,
      boot_device: boot_device,
      switch_name: switch_name,

      **attrs,

      _return_fields: self.class.attributes
    )
  )
  attributes.merge! post_create_attributes if post_create_attributes.any?
  save if dirty?

  # Save any associations that have been manually assigned before VM creation
  self.class.associations.each_key do |assoc|
    next unless associations.key? assoc

    associations[assoc].select do |obj|
      obj.computer_name = computer_name if obj.respond_to?(:computer_name=)
      obj.vm_id = id if obj.respond_to?(:vm_id=)

      obj.save if obj.dirty? || !obj.persisted?
      next if assoc != :vhd || hard_drives.none? { |hdd| hdd.path == vhd.path }

      hard_drives.create(path: vhd.path)
    end
    associations[assoc].clear
  end

  self
end

#destroy(underlying = nil) ⇒ Object

Note:

if the VM has VHDs, make sure to remove them first to not leave the VM data remaining on disk

Note:

underlying will remove the full path of the VM, make sure this is what you want before using it

Remove the VM object from Hyper-V

Parameters:

  • underlying (Boolean) (defaults to: nil) —

    remove the underlying configuration directory from disk on the Hyper-V host



323
324
325
326
327
328
329
330
331
332
333
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 323

def destroy(underlying = nil)
  underlying = true if underlying.nil? && attributes[:path]&.end_with?(attributes[:name])

  requires :id
  requires :path if underlying
  stop turn_off: true if ready?

  service.remove_vm(computer_name: computer_name, id: id)
  service.remove_item(path: path, computer_name: computer_name, recurse: true) if underlying
  true
end

#hibernate ⇒ Object

Hibernate the VM, i.e. save VM state to disk and turn it off



293
294
295
296
297
298
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 293

def hibernate
  requires :id

  service.save_vm(computer_name: computer_name, id: id)
  true
end

#ip_addresses ⇒ Array<String>

Returns the IP addresses of all attached network adapters.

Returns:

  • (Array<String>) —

    the IP addresses of all attached network adapters



477
478
479
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 477

def ip_addresses
  network_adapters.map(&:ip_addresses).flatten
end

#mac_addresses ⇒ Array<String>

Returns the MAC addresses of all attached network adapters.

Returns:

  • (Array<String>) —

    the MAC addresses of all attached network adapters



472
473
474
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 472

def mac_addresses
  network_adapters.map(&:mac_address)
end

#public_ip_address ⇒ String?

Returns the first public IP address of the VM - if any.

Returns:

  • (String, nil) —

    the first public IP address of the VM - if any



490
491
492
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 490

def public_ip_address
  public_ip_addresses.first
end

#public_ip_addresses ⇒ Array<String>

Returns the public (not link-local) IP addresses of all attached network adapters.

Returns:

  • (Array<String>) —

    the public (not link-local) IP addresses of all attached network adapters



482
483
484
485
486
487
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 482

def public_ip_addresses
  ip_addresses
    .map { |a| IPAddr.new a }
    .reject(&:link_local?)
    .map(&:to_s)
end

#ready? ⇒ Boolean

Returns if the VM is ready? (i.e. #state is :Running).

Returns:

  • (Boolean) —

    if the VM is ready? (i.e. #state is :Running)



467
468
469
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 467

def ready?
  state_num == 2
end

#reload ⇒ self?

Reload the VM attributes from the Hyper-V server

Returns:

  • (self) —

    if model successfully reloaded

  • (nil) —

    if something went wrong or the model was not found



432
433
434
435
436
437
438
439
440
441
442
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 432

def reload
  requires :id

  data = service.get_vm computer_name: computer_name, id: id, _return_fields: self.class.attributes
  return unless data

  merge_attributes(data)
  @old = data

  self
end

#restart ⇒ Object Also known as: reboot

Note:

This method will always cause a hard reset, i.e. power off and on without waiting for OS shutdown

Restart the VM



302
303
304
305
306
307
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 302

def restart
  requires :id

  service.restart_vm(computer_name: computer_name, id: id)
  true
end

#resume ⇒ Object

Resume suspended VM execution



285
286
287
288
289
290
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 285

def resume
  requires :id

  service.resume_vm(computer_name: computer_name, id: id)
  true
end

#start ⇒ Object

Start the VM



260
261
262
263
264
265
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 260

def start
  requires :id

  service.start_vm(computer_name: computer_name, id: id)
  true
end

#stop(turn_off: false) ⇒ Object

Stop the VM

Parameters:

  • turn_off (Boolean) (defaults to: false) —

    perform an instant power off instead of an ACPI shutdown



269
270
271
272
273
274
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 269

def stop(turn_off: false)
  requires :id

  service.stop_vm(computer_name: computer_name, id: id, turn_off: turn_off)
  true
end

#suspend ⇒ Object

Suspend VM execution



277
278
279
280
281
282
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 277

def suspend
  requires :id

  service.suspend_vm(computer_name: computer_name, id: id)
  true
end

#update ⇒ Object 



396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 396

def update
  requires :id

  changes = {
    processor_count: changed!(:processor_count),
    memory_startup_bytes: changed!(:memory_startup),
    new_vm_name: changed!(:name)
  }.compact
  if dynamic_memory_enabled
    changes[:dynamic_memory] = true if changed?(:dynamic_memory_enabled)
    changes[:memory_minimum_bytes] = memory_minimum if changed?(:dynamic_memory_enabled, :memory_minimum)
    changes[:memory_maximum_bytes] = memory_maximum if changed?(:dynamic_memory_enabled, :memory_maximum)
  elsif changed?(:dynamic_memory_enabled)
    changes[:static_memory] = true
  end
  changes.compact!

  changes[:notes] = notes || '' if changed? :notes
  return self unless changes.any?

  merge_attributes(
    service.set_vm(
      computer_name: old.computer_name,
      id: old.id,

      **changes,

      _always_include: changes.keys,
      _return_fields: self.class.attributes
    )
  )
end

#update_version ⇒ Object

Update the VM object to the latest version



311
312
313
314
315
316
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 311

def update_version
  requires :id

  service.update_vm(computer_name: computer_name, id: id)
  true
end

#username ⇒ String

Get the username of the main system account

Returns:

  • (String) —

    the system account username - usually “Administrator” or “root”



462
463
464
 
# File 'lib/fog/hyperv/compute/models/server.rb', line 462

def username
  @username || 'Administrator'
end