File Coverage

blib/lib/VMOMI.pm

Criterion	Covered	Total	%
statement	14	46	30.4
branch	0	18	0.0
condition	0	3	0.0
subroutine	5	6	83.3
pod	0	1	0.0
total	19	74	25.6

package VMOMI;

use 5.006;
use strict;
use warnings;

our $VERSION = 0.01;

use Class::Autouse;
use Exception::Class(
    'Exception',
    'Exception::SoapFault' => {
        isa     => 'Exception',
        fields  => [ 'faultcode', 'detail', 'faultstring' ] },
    'Exception::Autoload' => {
        isa     => 'Exception' },
    'Exception::Deserialize' => {
        isa     => 'Exception' },
    'Exception::Serialize' => {
        isa     => 'Exception' },
    'Exception::Protocol' => {
        isa     => 'Exception' },
);

Class::Autouse->autouse_recursive("VMOMI");

# TODO: Add support for multiple entity types in single call, e.g. 'HostSystem', 'VirtualMachine' & 'Folder'
sub find_entities {
    my ($content, $type, $match, $begin, %args) = @_;
    my (@properties, $spec, $view, $filter_spec, $result, @objects, @matched);

    $begin = $content->rootFolder unless defined $begin;
    @properties = keys %$match if defined $match;

    # PropertySpec
    $spec = new VMOMI::PropertySpec(type => $type, all => 0);
    if (defined $match) {
        $spec->pathSet(\@properties);
    }

    $view = $content->viewManager->CreateContainerView(
        type => [$type],
        recursive => 1,
        container => $begin->moref,
    );


    $filter_spec = new VMOMI::PropertyFilterSpec(
        reportMissingInResults => 0,
        propSet => [ new VMOMI::PropertySpec(
            all => 0,
            type => $type,
            pathSet => \@properties,
        )],
        objectSet => [ new VMOMI::ObjectSpec(
            obj => $view,
            skip => 0,
            selectSet => [ new VMOMI::TraversalSpec(
                path => "view",
                type => $view->{type},
            )],
        )],
    );

    $result = $content->propertyCollector->RetrievePropertiesEx(
        specSet => [$filter_spec],
        options => new VMOMI::RetrieveOptions(),
    );

    push @objects, @{ $result->objects || [ ] };
    while (defined $result->token) {
        $result = $content->propertyCollector->ContinueRetrievePropertiesEx(token => $result->token);
        push @objects, @{ $result->objects || [ ] };
    }


    unless (defined $match) {
        @matched = map { $_->obj } @objects;
        return @matched;
    }

    foreach my $object (@objects) {
        my (%pset);

        %pset = map { $_->name => $_->val } @{ $object->{propSet} || [ ] };
        foreach (@properties) {
            my $re = $match->{$_};

            if (not defined $re and not defined $pset{$_}) {
                push @matched, $object->obj;
            } # check if $re or $pset{$_} are undef to avoid compare errors

            if ($pset{$_} =~ /$re/) {
                push @matched, $object->obj;
            }
        }
    }
    return @matched;

}

1;

=encoding UTF-8

=head1 NAME

VMOMI - VMware vSphere API Perl Bindings

=head1 SYNOPSIS

    use VMOMI;

    stub = new VMOMI::SoapStub(host => $host) || die "Failed to initialize VMOMI::SoapStub";
    $instance = new VMOMI::ServiceInstance(
        $stub,
        new VMOMI::ManagedObjectReference(
            type  => 'ServiceInstance',
            value => 'ServiceInstance',
        ),
    );

    # Login
    $content = $instance->RetrieveServiceContent;
    $session = $content->sessionManager->Login(userName => $user, password => $pass);

    @vms = VMOMI::find_entities($content, 'VirtualMachine');
    foreach (@vms) {
        print $_->name . ", " . $_->config->guestFullName . "\n";
    }

    # Logout
    $content->sessionManager->Logout();

=head1 INSTALLATION

    cpanm install VMOMI

=head1 DESCRIPTION

VMOMI provides an alternative to the VMware Perl SDK for vSphere and was created to address
some limitations with the offical VMware Perl SDK.

=over 8

=item * B

=item * B>

=item * B

=back

=head2 Finding ManagedEntities

Managed entities in the VMware vSphere Web Service inventory, e.g. VirtualMachine or HostSystem, can be
fetched with the utilty function B:

    @vms = VMOMI::find_entities($content, 'VirtualMachine', { 'config.guestFullName' => qr/Linux/ });
    @hosts = VMOMI::find_entities($content, 'HostSystem');

B<$content> should be an authenticated instance of VMOMI::ServiceContent:

    $stub = new VMOMI::SoapStub(host => $host);
    $instance = new VMOMI::ServiceInstance(
        $stub,
        new VMOMI::ManagedObjectReference(
            type  => 'ServiceInstance',
            value => 'ServiceInstance',
        ),
    );
    $content = $instance->RetrieveServiceContent;
    $session = $content->sessionManager->Login(userName => $user, password => $pass);

=head2 Working with ManagedObjectReferences

The VMware vSphere Web Service API primarily works through ManagedObjectReferences (moref). Most SDKs
therefore generate "view classes" of the common objects managed through the API, e.g. VirtualMachine,
HostSystem, Folder, Datacenter, ClusterComputeResource, etc.

VMOMI provides similar, manually generated classes for these managed objects.  During deserialization
of the vSphere Web Service API, ManagedObjectReferences are automatically instantiated to corresponding
"view classes". The underlying ManagedObjectReference can be accessed through the B property.
ManagedObjectReferences have two properties B and B:

    $vm = VMOMI::find_entities($content, 'VirtualMachine', { name => qr/TestVM2/ })->shift;
    $moref = $vm->moref;
    print $moref->type . ":" . $moref->value . "\n"; # 'VirtualMachine:vm-12'

"View" classes can instantiated using known, valid ManagedObjectReference type and value properties along
with a current, authenticated connection stub:

    $vm = new VMOMI::VirtualMachine(
        $stub,
        new VMOMI::ManagedObjectReference
            type => 'VirtualMachine',
            value => 'vm-12'),
    );
    print $vm->name . "\n"; # TestVM2

=head2 Performance Considerations

Properties are only retrieved from the vSphere Web Services API on access through AUTOLOAD, and as such
can impact performance in iterations. The following logic will invoke three API calls to vSphere for each
virtual machine:

    @vms = VMOMI::find_entities($content, 'VirtualMachine');
    foreach (@vms) {
        print $_->name . ": " . $_->runtime->powerState . "\n"; # three API invocations
    }

As future enhancement, preserving values previously fetched from the API to avoid reptitive calls would
improve performance. As a work around, pulling requested properties in bulk through
B or B and parsing them into
a data structure will provide the best performance.

=head1 AUTHOR

Reuben M. Stump

[e-mail]

=head1 SEE ALSO

L

L

=head1 COPYRIGHT and LICENSE

Copyright (c) 2015 by Reuben M. Stump

This code is distributed under the Apache 2 License. The full text of the license can be found in the
LICENSE file included with this module.


=cut