/ 
WWW-Hetzner-0.002
/ WWW::Hetzner::Cloud::API::Servers

NAME

WWW::Hetzner::Cloud::API::Servers - Hetzner Cloud Servers API

VERSION

version 0.002

SYNOPSIS

use WWW::Hetzner::Cloud;

my $cloud = WWW::Hetzner::Cloud->new(token => $ENV{HETZNER_API_TOKEN});

# List all servers
my $servers = $cloud->servers->list;

# Create a server
my $server = $cloud->servers->create(
    name        => 'my-server',
    server_type => 'cx22',
    image       => 'debian-12',
    location    => 'fsn1',
    ssh_keys    => ['my-key'],
    labels      => { env => 'prod' },
);

# Server is a WWW::Hetzner::Cloud::Server object
print $server->id, "\n";
print $server->ipv4, "\n";

# Wait for server to be running
$cloud->servers->wait_for_status($server->id, 'running');

# Power actions via API
$cloud->servers->shutdown($server->id);

# Or directly on the object
$server->power_on;
$server->shutdown;

# Update server
$server->name('new-name');
$server->update;

# Delete server
$server->delete;

DESCRIPTION

This module provides the API for managing Hetzner Cloud servers. All methods return WWW::Hetzner::Cloud::Server objects.

list

my $servers = $cloud->servers->list;
my $servers = $cloud->servers->list(label_selector => 'env=prod');

Returns an arrayref of WWW::Hetzner::Cloud::Server objects. Optional parameters: label_selector, name, status, sort.

list_by_label

my $servers = $cloud->servers->list_by_label('env=production');

Convenience method to list servers by label selector.

get

my $server = $cloud->servers->get($id);

Returns a WWW::Hetzner::Cloud::Server object.

create

my $server = $cloud->servers->create(
    name        => 'my-server',      # required
    server_type => 'cx23',           # required
    image       => 'debian-13',      # required
    location    => 'fsn1',           # optional
    datacenter  => 'fsn1-dc14',      # optional (alternative to location)
    ssh_keys    => ['my-key'],       # optional
    labels      => { env => 'prod' },# optional
    user_data   => '...',            # optional (cloud-init)
    start_after_create => 1,         # optional (default: true)
    placement_group => 'my-group',   # optional
    networks    => [123, 456],       # optional (network IDs)
    volumes     => [789],            # optional (volume IDs)
    automount   => 1,                # optional (automount volumes)
    firewalls   => [111, 222],       # optional (firewall IDs)
    enable_ipv4 => 1,                # optional (default: true)
    enable_ipv6 => 1,                # optional (default: true)
    ipv4        => 'primary-ip-id',  # optional (existing Primary IP)
    ipv6        => 'primary-ip-id',  # optional (existing Primary IP)
);

Creates a new server. Returns a WWW::Hetzner::Cloud::Server object.

delete

$cloud->servers->delete($id);

Deletes a server.

power_on

$cloud->servers->power_on($id);

Powers on a server.

power_off

$cloud->servers->power_off($id);

Hard power off (like pulling the power cord).

reboot

$cloud->servers->reboot($id);

Hard reboot.

shutdown

$cloud->servers->shutdown($id);

Graceful shutdown via ACPI.

rebuild

$cloud->servers->rebuild($id, 'debian-13');

Rebuilds server with a new image. Data on the server will be lost.

change_type

$cloud->servers->change_type($id, 'cx33', upgrade_disk => 1);

Changes server type. Server must be powered off.

reset

$cloud->servers->reset($id);

Hard reset the server.

enable_rescue

$cloud->servers->enable_rescue($id, type => 'linux64', ssh_keys => ['my-key']);

Enable rescue mode for the server.

disable_rescue

$cloud->servers->disable_rescue($id);

Disable rescue mode for the server.

request_console

$cloud->servers->request_console($id);

Request a VNC console for the server.

reset_password

$cloud->servers->reset_password($id);

Reset the root password of the server.

attach_iso

$cloud->servers->attach_iso($id, $iso);

Attach an ISO to the server.

detach_iso

$cloud->servers->detach_iso($id);

Detach an ISO from the server.

enable_backup

$cloud->servers->enable_backup($id);

Enable automatic backups for the server.

disable_backup

$cloud->servers->disable_backup($id);

Disable automatic backups for the server.

update

$cloud->servers->update($id, name => 'new-name', labels => { env => 'dev' });

Updates server name or labels.

wait_for_status

$cloud->servers->wait_for_status($id, 'running', 120);

Polls until server reaches the specified status. Default timeout is 120 seconds.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-www-hetzner/issues.

IRC

Join #kubernetes on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

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