NAME

WebService::Scaleway - Perl interface to Scaleway cloud server provider API

SYNOPSIS

  use WebService::Scaleway;
  my $token = ...; # API token here
  my $sw = WebService::Scaleway->new($token);
  my $org = $sw->organizations;

  # Create an IP, a volume, and use them for a new Debian Jessie server
  my $ip = $sw->create_ip($org);
  my $vol = $sw->create_volume('testvol', $org, 'l_ssd', 50_000_000_000);
  my ($debian) = grep { $_->name =~ /debian jessie/i } $sw->images;
  my $srv = $sw->create_server('testsrv', $org, $debian, {1 => $vol->id});

  # Now we have a server, an IP, and two volumes (the root volume with
  # Debian Jessie, and the extra volume we just created).

  # Change the server name
  $srv->{name} = 'Debian';
  $sw->update_server($srv);

  # Boot the server
  $sw->perform_server_action($srv, 'poweron');
  say "The server is now booting. To access it, do ssh root@", $ip->address;

DESCRIPTION

Scaleway is an IaaS provider that offers bare metal ARM cloud servers. WebService::Scaleway is a Perl interface to the Scaleway API.

Constructors

WebService::Scaleway objects are defined by their authentication token. There are two consructors:

WebService::Scaleway->new($auth_token)

Construct a WebService::Scaleway object from a given authentication token.

WebService::Scaleway->new($email, $password)

Construct a WebService::Scaleway object from an authentication token obtained by logging in with the given credentials.

Listing resources

These methods return a list of all resources of a given type associated to your account. Each resource is a blessed hashref with AUTOLOADed accessors (for example $resource->{name} can be written as $resource->name) and that stringifies to the ID of the resource: $resource->id.

There is no difference between resources() and list_resources().

$self->tokens
$self->list_tokens

Official documentation: https://developer.scaleway.com/#tokens-tokens-get.

$self->organizations
$self->list_organizations

Official documentation: https://developer.scaleway.com/#organizations-organizations.

$self->servers
$self->list_servers

Official documentation: https://developer.scaleway.com/#servers-servers-get.

$self->volumes
$self->list_volumes

Official documentation: https://developer.scaleway.com/#volumes-volumes-get.

$self->snapshots
$self->list_snapshots

Official documentation: https://developer.scaleway.com/#snapshots-snapshots-get.

$self->images
$self->list_images

Official documentation: https://developer.scaleway.com/#images-images-get.

$self->ips
$self->list_ips

Official documentation: https://developer.scaleway.com/#ips-ips-get.

$self->security_groups
$self->list_security_groups

Official documentation: https://developer.scaleway.com/#security-groups-security-groups-get.

$self->security_group_rules($group_id)
$self->list_security_group_rules($group_id)

Official documentation: https://developer.scaleway.com/#security-groups-manage-rules-get.

Retrieving resources

These methods take the ID of a resource and return the resource as a blessed hashref as described in the previous section.

You can pass a blessed hashref instead of a resource ID, and you'll get a fresh version of the object passed. Useful if something updated the object in the meantime.

There is no difference between resource($id) and get_resource($id).

$self->token($id)
$self->get_token($id)

Official documentation: https://developer.scaleway.com/#tokens-token-get.

$self->user($id)
$self->get_user($id)

Official documentation: https://developer.scaleway.com/#users-user.

$self->server($id)
$self->get_server($id)

Official documentation: https://developer.scaleway.com/#servers-server-get.

$self->volume($id)
$self->get_volume($id)

Official documentation: https://developer.scaleway.com/#volumes-volume-get.

$self->snapshot($id)
$self->get_snapshot($id)

Official documentation: https://developer.scaleway.com/#snapshots-snapshot-get.

$self->image($id)
$self->get_image($id)

Official documentation: https://developer.scaleway.com/#images-operation-on-a-single-image-get.

$self->ip($id)
$self->get_ip($id)

Official documentation: https://developer.scaleway.com/#ips-ip-get.

$self->security_group($id)
$self->get_security_group($id)

Official documentation: https://developer.scaleway.com/#security-groups-operation-on-a-security-groups-get.

$self->security_group_rule($group_id, $rule_id)
$self->get_security_group_rule($group_id, $rule_id)

Official documentation: https://developer.scaleway.com/#security-groups-operation-on-a-security-rule-get.

Deleting resources

These methods take the ID of a resource and delete it. They do not return anything. You can pass a blessed hashref instead of a resource ID.

$self->delete_token($id)

Official documentation: https://developer.scaleway.com/#tokens-token-delete.

$self->delete_server($id)

Official documentation: https://developer.scaleway.com/#servers-server-delete.

$self->delete_volume($id)

Official documentation: https://developer.scaleway.com/#volumes-volume-delete.

$self->delete_snapshot($id)

Official documentation: https://developer.scaleway.com/#snapshots-snapshot-delete.

$self->delete_image($id)

Official documentation: https://developer.scaleway.com/#images-operation-on-a-single-image-delete.

$self->delete_ip($id)

Official documentation: https://developer.scaleway.com/#ips-ip-delete.

$self->delete_security_group($id)

Official documentation: https://developer.scaleway.com/#security-groups-operation-on-a-security-groups-delete.

$self->delete_security_group_rule($group_id, $rule_id)

Official documentation: https://developer.scaleway.com/#security-groups-operation-on-a-security-rule-delete.

Modifying resources

These methods take a hashref representing a resource that already exists and update it. The value of $resource->{id} is used for identifying this resource on the remote end. Both blessed and unblessed hashrefs are accepted. The updated resource is returned as a blessed hashref as described in "Listing resources".

$self->update_server($resource)

Official documentation: https://developer.scaleway.com/#servers-server-put.

$self->update_snapshot($resource)

Official documentation: https://developer.scaleway.com/#snapshots-snapshot-put.

$self->update_image($resource)

Official documentation: https://developer.scaleway.com/#images-operation-on-a-single-image-put.

$self->update_ip($resource)

Official documentation: https://developer.scaleway.com/#ips-ip-put.

$self->update_security_group($resource)

Official documentation: https://developer.scaleway.com/#security-groups-operation-on-a-security-groups-put.

$self->update_security_group_rule($group_id, $resource)

Official documentation: https://developer.scaleway.com/#security-groups-operation-on-a-security-rule-put.

Creating resources

These methods take either a hash that is passed directly to the API or a method-specific list of positional parameters. They create a new resource and return it as a blessed hashref as described in "Listing resources".

When using positional parameters, you can pass a resource in blessed hashref format where a resource ID is expected, unless the method's documentation says otherwise.

Most of these methods require an organization ID. You can obtain it with the organizations method described above.

$self->create_token(\%data)
$self->create_token($email, $password, [$expires])

Authenticates a user against their username and password and returns an authentication token. If $expires (default: false) is true, the token will expire.

This method is called internally by the two-argument constructor.

Official documentation: https://developer.scaleway.com/#tokens-tokens-get.

$self->create_server(\%data)
$self->create_server($name, $organization, $image, $volumes, [$tags])

Creates and returns a new server.

$name is the server name. $organization is the organization ID. $image is the image ID. $volumes is a "sparse array" (hashref from indexes to volume IDs, indexed from 1) of extra volumes (that is, volumes other than the root volume). $tags is an optional arrayref of tags.

For the $volumes parameter you can pass hashrefs that describe volumes instead of volume IDs. This will create new volumes. The hashrefs are (presumably) passed to create_volume. An example inspired by the official documentation:

  $volumes = { 1 => {
    name         => "vol_demo",
    organization => "ecc1c86a-eabb-43a7-9c0a-77e371753c0a",
    size         => 10_000_000_000,
    volume_type  => "l_sdd",
  }};

Note that there may not be any blessed hashrefs inside $volumes.

Official documentation: https://developer.scaleway.com/#servers-servers-get.

$self->create_volume(\%data)
$self->create_volume($name, $organization, $volume_type, $size)

Creates and returns a new volume. $volume_type currently must be l_ssd. $size is the size in bytes.

Official documentation: https://developer.scaleway.com/#volumes-volumes-get.

$self->create_snapshot(\%data)
$self->create_snapshot($name, $organization, $volume_id)

Creates and returns a snapshot of the volume $volume_id.

Official documentation: https://developer.scaleway.com/#snapshots-snapshots-get.

$self->create_image(\%data)
$self->create_image($name, $organization, $root_volume, $arch)

Creates and returns an image from the volume $root_volume. $arch is the architecture of the image (currently must be "arm").

Official documentation: https://developer.scaleway.com/#images-images-get.

$self->create_ip(\%data)
$self->create_ip($organization)

Official documentation: https://developer.scaleway.com/#ips-ips-get.

$self->create_security_group(\%data)
$self->create_security_group($name, $organization, $description)

Official documentation: https://developer.scaleway.com/#security-groups-security-groups-get.

$self->create_security_group_rule($group_id)
$self->create_security_group_rule($group_id, $organization, $action, $direction, $ip_range, $protocol, [<$dest_port_from>])

Official documentation: https://developer.scaleway.com/#security-groups-manage-rules-get.

Miscellaneous methods

These are methods that don't fit any previous category. Any use of "blessed hashref" refers to the concept described in "Listing resources". Wherever a resource ID is expected, you can instead pass a resource as a blessed hashref and the method will call ->id on it for you.

$self->server_actions($server_id)
$self->list_server_actions($server_id)

Returns a list of strings representing possible actions you can perform on the given server. Example actions are powering on/off a server or rebooting it.

Official documentation: https://developer.scaleway.com/#servers-actions-get

$self->perform_server_action($server_id, $action)

Performs an action on a server. $action is one of the strings returned by server_actions. The function returns a blessed hashref with information about the task.

This is not very useful, as this module does not currently offer any function for tracking tasks.

Official documentation: https://developer.scaleway.com/#servers-actions-post

$self->refresh_token($token_id)

This method takes the ID of an expirable token, extends its expiration date by 30 minutes, and returns the new token as a blessed hashref.

Official documentation: https://developer.scaleway.com/#tokens-token-patch

$self->server_metadata

This method can only be called from a Scaleway server. It returns information about the server as a blessed hashref.

Official documentation: https://developer.scaleway.com/#metadata-c1-server-metadata

SEE ALSO

https://developer.scaleway.com/

AUTHOR

Marius Gavrilescu, <marius@ieval.ro>

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Marius Gavrilescu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.20.2 or, at your option, any later version of Perl 5 you may have available.