The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
DigitalOcean-0.17
River stage zero No dependents
7 ++
/ DigitalOcean::Droplet

NAME

DigitalOcean::Droplet - Represents a Droplet object in the DigitalOcean API

VERSION

version 0.17

SYNOPSIS

    FILL ME IN

DESCRIPTION

FILL ME IN

METHODS

path

Returns the api path for this droplet.

kernels

This will retrieve a list of all kernels available to a Dropet by returning a DigitalOcean::Collection that can be used to iterate through the DigitalOcean::Kernels objects of the kernels collection.

    my $kernels_collection = $droplet->kernels;
    my $obj;

    while($obj = $kernels_collection->next) { 
        print $obj->name . "\n";
    }

If you would like a different per_page value to be used for this collection instead of per_page, it can be passed in as a parameter:

    #set default for all collections to be 30
    $do->per_page(30);

    #set this collection to have 2 objects returned per page
    my $kernels_collection = $droplet->kernels(2);
    my $obj;

    while($obj = $kernels_collection->next) { 
        print $obj->name . "\n";
    }

snapshots

This will retrieve the snapshots that have been created from a Droplet by returning a DigitalOcean::Collection that can be used to iterate through the DigitalOcean::Snapshot objects of the snapshots collection.

    my $snapshots_collection = $droplet->snapshots;
    my $obj;

    while($obj = $snapshots_collection->next) { 
        print $obj->name . "\n";
    }

If you would like a different per_page value to be used for this collection instead of per_page, it can be passed in as a parameter:

    #set default for all collections to be 30
    $do->per_page(30);

    #set this collection to have 2 objects returned per page
    my $snapshots_collection = $droplet->snapshots(2);
    my $obj;

    while($obj = $snapshots_collection->next) { 
        print $obj->name . "\n";
    }

backups

This will retrieve the backups that have been created from a Droplet by returning a DigitalOcean::Collection that can be used to iterate through the DigitalOcean::Backup objects of the backups collection.

    my $backups_collection = $droplet->backups;
    my $obj;

    while($obj = $backups_collection->next) { 
        print $obj->name . "\n";
    }

If you would like a different per_page value to be used for this collection instead of per_page, it can be passed in as a parameter:

    #set default for all collections to be 30
    $do->per_page(30);

    #set this collection to have 2 objects returned per page
    my $backups_collection = $droplet->backups(2);
    my $obj;

    while($obj = $backups_collection->next) { 
        print $obj->name . "\n";
    }

actions

This will retrieve all actions that have been executed on a Droplet by returning a DigitalOcean::Collection that can be used to iterate through the DigitalOcean::Action objects of the actions collection.

    my $actions_collection = $droplet->actions;
    my $obj;

    while($obj = $actions_collection->next) { 
        print $obj->id . "\n";
    }

If you would like a different per_page value to be used for this collection instead of per_page, it can be passed in as a parameter:

    #set default for all collections to be 30
    $do->per_page(30);

    #set this collection to have 2 objects returned per page
    my $actions_collection = $droplet->actions(2);
    my $obj;

    while($obj = $actions_collection->next) { 
        print $obj->id . "\n";
    }

delete

This deletes the droplet. This will return 1 on success and undef on failure.

    $droplet->delete;
    #droplet now gone

neighbors

This method returns all of the droplets that are running on the same physical server as the DigitalOcean::Droplet object this method is called with. It returns an array reference.

    my $neighbors = $droplet->neighbors;

    for my $neighbor (@$neighbors) { 
        print $neighbor->name . "\n";
    }

action

This will retrieve an action associated with the DigitalOcean::Droplet object by id and return a DigitalOcean::Action object.

    my $action = $droplet->action(56789);

disable_backups

This method disables backups on your droplet. It returns a DigitalOcean::Action object.

    my $action = $droplet->disable_backups;

reboot

This method allows you to reboot a droplet. This is the preferred method to use if a server is not responding. It returns a DigitalOcean::Action object.

    my $action = $droplet->reboot;

A reboot action is an attempt to reboot the Droplet in a graceful way, similar to using the reboot command from the console.

power_cycle

This method allows you to power cycle a droplet. This will turn off the droplet and then turn it back on. It returns a DigitalOcean::Action object.

    my $action = $droplet->power_cycle;

A powercycle action is similar to pushing the reset button on a physical machine, it's similar to booting from scratch.

shutdown

This method allows you to shutdown a running droplet. The droplet will remain in your account. It returns a DigitalOcean::Action object.

    my $action = $droplet->shutdown;

A shutdown action is an attempt to shutdown the Droplet in a graceful way, similar to using the shutdown command from the console. Since a shutdown command can fail, this action guarantees that the command is issued, not that it succeeds. The preferred way to turn off a Droplet is to attempt a shutdown, with a reasonable timeout, followed by a power off action to ensure the Droplet is off.

power_off

This method allows you to poweroff a running droplet. The droplet will remain in your account. It returns a DigitalOcean::Action object.

    my $action = $droplet->power_off;

A power_off event is a hard shutdown and should only be used if the shutdown action is not successful. It is similar to cutting the power on a server and could lead to complications.

power_on

This method allows you to poweron a powered off droplet. It returns a DigitalOcean::Action object.

    my $action = $droplet->power_on;

restore

This method allows you to restore a droplet with a previous image or snapshot. This will be a mirror copy of the image or snapshot to your droplet. Be sure you have backed up any necessary information prior to restore. It returns a DigitalOcean::Action object.

  • image Required, string if an image slug. number if an image ID., An image slug or ID. This represents the image that the Droplet will use as a base.

    my $action = $droplet->restore(image => 56789);

A Droplet restoration will rebuild an image using a backup image. The image ID that is passed in must be a backup of the current Droplet instance. The operation will leave any embedded SSH keys intact.

password_reset

This method will reset the root password for a droplet. Please be aware that this will reboot the droplet to allow resetting the password. It returns a DigitalOcean::Action object.

    my $action = $droplet->password_reset;

resize

This method allows you to resize a specific droplet to a different size. It returns a DigitalOcean::Action object.

  • disk Optional, Boolean (1 or undef), Whether to increase disk size

  • size Required, String, The size slug that you want to resize to.

    my $action = $droplet->resize(
        disk => 1,
        size => '1gb', 
    );

In order to resize your droplet, it must first be powered off, and you must wait for the droplet to be powered off before you can call resize on the droplet. Making the call accurately would look something like this:

    $droplet->power_off(wait_on_action => 1);

    my $action = $droplet->resize(
        disk => 1,
        size => '1gb', 
        wait_on_action => 1,
    );

    $droplet->power_on(wait_on_action => 1);

If your droplet is already on and you want to resize it and boot your droplet back up, you can call "resize_reboot" to do the above code for you.

resize_reboot

In order to call "resize_reboot", your droplet must be powered off. If your droplet is already running, this method makes a call to resize for you and powers off your droplet, and then powers it on after it is done resizing and handles waiting on each event to finish so you do not have to write this code. This is essentially the code that "resize_reboot" performs for you:

    $droplet->power_off(wait_on_action => 1);

    $droplet->resize(
        disk => $disk,
        size => $size,
        wait_on_action => 1,
    );

    $droplet->power_on(wait_on_event => 1);

So a call to "resize_reboot" would look like:

    my $actions = $droplet->resize_reboot(
        disk => 1,
        size => '1gb', 
    );

    for my $action (@$actions) { 
        print $action->id . ' ' . $action->status . "\n";
    }

It returns an array reference of all three actions returned by "power_off", "resize", and "power_on".

rebuild

This method allows you to rebuild a Droplet. It returns a DigitalOcean::Action object. A rebuild action functions just like a new create. This is useful if you want to start again but retain the same IP address for your droplet.

  • image Required, string if an image slug. number if an image ID., An image slug or ID. This represents the image that the Droplet will use as a base.

    my $action = $droplet->rebuild(
        image => 'ubuntu-14-04-x64',
    );

rename

This method renames the droplet to the specified name. The new name is reflected in the DigitalOcean::Droplet object. It returns a DigitalOcean::Action object.

  • name Required, String, The new name for the Droplet.

    $droplet->rename(name => $new_name);

change_kernel

This method allows you to change the kernel of a Droplet. It returns a DigitalOcean::Action object.

  • kernel Required, Number, A unique number used to identify and reference a specific kernel.

    my $action = $droplet->change_kernel(kernel => 991);

change_kernel_reboot

In order for a new kernel to be active, the machine must be powered off and then powered on. This function changes the kernel for you and powers off your droplet, and then powers it on. It also handles waiting on each event so you do not have to write this code. This is essentially the code that "change_kernel_reboot" performs for you:

    $droplet->change_kernel(kernel => $kernel);
    $droplet->power_off(wait_on_action => 1);
    $droplet->power_on(wait_on_event => 1);

So a call to "change_kernel_reboot" would look like:

    my $actions = $droplet->change_kernel_reboot(kernel => 991);

    for my $action (@$actions) { 
        print $action->id . ' ' . $action->status . "\n";
    }

It returns an array reference of all three actions returned by "change_kernel", "power_off", and "power_on".

enable_ipv6

This method allows you to enable IPv6 networking on an existing Droplet (within a region that has IPv6 available). It returns a DigitalOcean::Action object.

    my $action = $droplet->enable_ipv6;

enable_private_networking

This method allows you to enable private networking on an existing Droplet (within a region that has private networking available). It returns a DigitalOcean::Action object.

    my $action = $droplet->enable_private_networking;

In order to enable private networking for your droplet, it must first be powered off, and you must wait for the droplet to be powered off before you can call snapshot on the droplet. Making the call accurately would look something like this:

    $droplet->power_off(wait_on_event => 1);
    $droplet->enable_private_networking(wait_on_event => 1);
    $droplet->power_on(wait_on_event => 1);

If your droplet is already on and you want to enable private networking and boot your droplet back up, you can call "enable_private_networking_reboot" to do the above code for you.

enable_private_networking_reboot

In order to call "enable_private_networking", your droplet must be powered off. If your droplet is already running, this method makes a call to "enable_private_networking" for you and powers off your droplet, and then powers it on after it is done and handles waiting on each event to finish so you do not have to write this code. This is essentially the code that "enable_private_networking" performs for you:

    $droplet->power_off(wait_on_action => 1);

    $droplet->enable_private_networking(wait_on_action => 1);

    $droplet->power_on(wait_on_event => 1);

So a call to "enable_private_networking_reboot" would look like:

    my $actions = $droplet->enable_private_networking_reboot;

    for my $action (@$actions) { 
        print $action->id . ' ' . $action->status . "\n";
    }

It returns an array reference of all three actions returned by "power_off", "enable_private_networking", and "power_on".

snapshot

This method allows you to take a snapshot of the droplet once it has been powered off, which can later be restored or used to create a new droplet from the same image.

  • name Optional, String, this is the name of the new snapshot you want to create. If not set, the snapshot name will default to date/time

In order to take a snapshot of your droplet, it must first be powered off, and you must wait for the droplet to be powered off before you can call snapshot on the droplet. Making the call accurately would look something like this:

    $droplet->power_off(wait_on_event => 1);
    $droplet->snapshot;

If your droplet is already on and you essentially want to take a snapshot and boot your droplet back up, you can call L/snapshot_reboot> to do the above code for you. (The "snapshot" method turns the droplet back on for you).

upgrade

This method allows you to upgrade a droplet. It returns a DigitalOcean::Action object.

    my $action = $droplet->upgrade;

id

Actions

snapshot_reboot

If your droplet is already running, this method makes a call to "snapshot" for you and powers off your droplet, and then powers it on after it is done taking a snapshot and handles waiting on each event to finish so you do not have to write this code. This is essentially the code that "snapshot_reboot" performs for you:

    $droplet->power_off(wait_on_event => 1);
    $droplet->snapshot(wait_on_event => 1); #snapshot powers your droplet back on for you

So a call to "snapshot_reboot" would look like:

    my $actions = $droplet->snapshot_reboot;

    for my $action (@$actions) { 
        print $action->id . ' ' . $action->status . "\n";
    }

It returns an array reference of both actions returned by "power_off", "snapshot_reboot".

AUTHOR

Adam Hopkins <srchulo@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019 by Adam Hopkins.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.