]> iEval git - webservice-scaleway.git/blame - lib/WebService/Scaleway.pm
Fix perform_server_action
[webservice-scaleway.git] / lib / WebService / Scaleway.pm
CommitLineData
362a19d8
MG
1package WebService::Scaleway;
2
3use 5.014000;
4use strict;
5use warnings;
6
7our $VERSION = '0.001';
8
9use Carp qw/croak/;
10use HTTP::Tiny;
11use JSON::MaybeXS;
12use Scalar::Util qw/blessed/;
13
14my $ht = HTTP::Tiny->new(
15 agent => "WebService-Scaleway/$VERSION ",
16 verify_SSL => 1,
17);
18
19# Instance of WebService::Scaleway with no API key
20# Used to create tokens from email/password
21my $dummy = '';
22$dummy = bless \$dummy, __PACKAGE__;
23
24sub _account ($) { "https://account.scaleway.com$_[0]"}
25sub _api ($) { "https://api.scaleway.com$_[0]" }
26
27sub _request {
28 my ($self, $method, $url, $opts) = @_;
29 $opts->{headers} //= {};
30 $opts->{headers}{'X-Auth-Token'} = $$self if $$self;
31 $opts->{headers}{'Content-Type'} = 'application/json';
32 my $ret = $ht->request($method, $url, $opts);
33 die 'Request to Scaleway API server was unsuccessful: ' . $ret->{status} . ' ' . $ret->{reason} . '; ' . $ret->{content} unless $ret->{success};
34
35 decode_json $ret->{content} if $ret->{status} != 204;
36}
37
38sub _get { shift->_request(GET => @_) }
39sub _post { shift->_request(POST => @_) }
40sub _patch { shift->_request(PATCH => @_) }
41sub _put { shift->_request(PUT => @_) }
42sub _delete { shift->_request(DELETE => @_) }
43
44sub _tores {
45 my @ret = map { bless $_, 'WebService::Scaleway::Resource' } @_;
46 wantarray ? @ret : $ret[0]
47}
48
49sub new {
50 my ($class, $token) = @_;
51 $token = $dummy->create_token(@_[1..$#_])->id if @_ > 2;
52
53 bless \$token, $class
54}
55
56BEGIN {
57 my @account_res = qw/token organization user/;
58 my @api_res = qw/server volume snapshot image ip security_group/;
59
60 my %res = (
61 map ({ $_ => _account "/${_}s" } @account_res),
62 map { $_ => _api "/${_}s" } @api_res);
63
64 my %create_parms = (
65 token => [qw/email password expires/],
66 server => [qw/name organization image volumes tags/],
67 volume => [qw/name organization volume_type size/],
68 snapshot => [qw/name organization volume_id/],
69 image => [qw/name organization root_volume arch/],
70 ip => [qw/ organization/],
71 security_group => [qw/name organization description/],
72 );
73
74 sub dynsub {
75 no strict 'refs';
76 my $sub = pop;
77 *$_ = $sub for @_
78 }
79
80 for my $res (keys %res) {
81 dynsub $res, "get_$res", sub {
82 local *__ANON__ = $res;
83 _tores shift->_get("$res{$res}/$_[0]")->{$res}
84 };
85
86 dynsub $res.'s', "list_$res".'s', sub {
87 local *__ANON__ = $res.'s';
88 my @ret = _tores @{shift->_get($res{$res})->{$res.'s'}};
89 wantarray ? @ret : $ret[0]
90 };
91
92 dynsub "delete_$res", sub {
93 local *__ANON__ = "delete_$res";
94 shift->_delete("$res{$res}/$_[0]")
95 };
96
97 dynsub "create_$res", sub {
98 local *__ANON__ = "create_$res";
99 my $self = shift;
100 my $content = $_[0];
101 if (blessed $content || ref $content ne 'HASH') {
102 croak "create_$res does not understand positional parameters, pass a hashref instead\n" unless $create_parms{$res};
103 my @parms = @{$create_parms{$res}};
104 $content = { map {
105 $parms[$_] => (blessed $_[$_] ? $_[$_]->id : $_[$_]) } 0 .. $#_ };
106 }
107 _tores $self->_post($res{$res}, { content => encode_json $content })->{$res}
108 };
109
110 dynsub "update_$res", sub {
111 local *__ANON__ = "update_$res";
112 my $data = blessed $_[1] ? {%{$_[1]}} : $_[1];
113 shift->_put("$res{$res}/".$data->{id}, { content => encode_json $data })
114 };
115 }
116}
117
118sub security_group_rule {
119 _tores shift->_get(_api "/security_groups/$_[0]/rules/$_[1]")->{rule}
120}
121
122sub security_group_rules {
123 _tores @{shift->_get(_api "/security_groups/$_[0]/rules")->{rules}}
124}
125
126BEGIN {
127 *get_security_group_rule = \&security_group_rule;
128 *list_security_group_rule = \&security_group_rules;
129}
130
131sub delete_security_group_rule {
132 shift->_delete(_api "/security_groups/$_[0]/rules/$_[1]")
133}
134
135sub create_security_group_rule {
136 my $self = shift;
137 my $grp = shift;
138 my $content = $_[0];
139 unless (ref $content eq 'HASH') {
140 my @parms = qw/organization action direction ip_range protocol dest_port_from/;
141 $content = { map { $parms[$_] => $_[$_] } 0 .. $#_ };
142 }
143 $self->_post(_api "/security_groups/$grp/rules", { content => encode_json $content })
144}
145
146sub update_security_group_rule {
147 my $data = blessed $_[2] ? {%{$_[2]}} : $_[2];
148 shift->_put (_api "/security_groups/$_[0]/rules/".$data->{id}, { content => encode_json $data })
149}
150
151sub server_actions {
152 @{shift->_get(_api "/servers/$_[0]/action")->{actions}}
153}
154
155BEGIN { *list_server_actions = \&server_actions }
156
157sub perform_server_action {
b292204e 158 my $content = encode_json { action => $_[2] };
362a19d8
MG
159 _tores shift->_post(_api "/servers/$_[0]/action", { content => $content })->{task};
160}
161
162sub refresh_token {
163 _tores shift->_patch(_account "/tokens/$_[0]")->{token}
164}
165
166sub server_metadata {
167 _tores $dummy->_get('http://169.254.42.42/conf?format=json')
168}
169
170package # hide from PAUSE
171 WebService::Scaleway::Resource;
172
173use overload '""' => sub { shift->id };
174
175our $AUTOLOAD;
176sub AUTOLOAD {
177 my ($self) = @_;
178 my ($attr) = $AUTOLOAD =~ m/::([^:]*)$/s;
179 die "No such attribute: $attr" unless exists $self->{$attr};
180 $self->{$attr}
181}
182
183sub can {
184 my ($self, $sub) = @_;
185 exists $self->{$sub} ? sub { shift->{$sub} } : undef
186}
187
188sub DESTROY {} # Don't call AUTOLOAD on destruction
189
1901;
191__END__
192
193=encoding utf-8
194
195=head1 NAME
196
197WebService::Scaleway - Perl interface to Scaleway cloud server provider API
198
199=head1 SYNOPSIS
200
201 use WebService::Scaleway;
202 my $token = ...; # API token here
203 my $sw = WebService::Scaleway->new($token);
204 my $org = $sw->organizations;
205
206 # Create an IP, a volume, and use them for a new Debian Jessie server
207 my $ip = $sw->create_ip($org);
208 my $vol = $sw->create_volume('testvol', $org, 'l_ssd', 50_000_000_000);
209 my ($debian) = grep { $_->name =~ /debian jessie/i } $sw->images;
210 my $srv = $sw->create_server('testsrv', $org, $debian, {1 => {%$vol}});
211
212 # Change the server name
213 $srv->{name} = 'Debian';
214 $sw->update_server($srv);
215
216 # Boot the server
217 $sw->perform_server_action($srv, 'poweron');
218 say "The server is now booting. To access it, do ssh root@", $ip->address;
219
220=head1 DESCRIPTION
221
222Scaleway is an IaaS provider that offers bare metal ARM cloud servers.
223WebService::Scaleway is a Perl interface to the Scaleway API.
224
225=head2 Constructors
226
227WebService::Scaleway objects are defined by their authentication
228token. There are two consructors:
229
230=over
231
232=item WebService::Scaleway->B<new>(I<$auth_token>)
233
234Construct a WebService::Scaleway object from a given authentication
235token.
236
237=item WebService::Scaleway->B<new>(I<$email>, I<$password>)
238
239Construct a WebService::Scaleway object from an authentication token
240obtained by logging in with the given credentials.
241
242=back
243
244=head2 Listing resources
245
246These methods return a list of all resources of a given type
247associated to your account. Each resource is a blessed hashref with
248C<AUTOLOAD>ed accessors (for example C<< $resource->{name} >> can be
249written as C<< $resource->name >>) and that stringifies to the ID of
250the resource: C<< $resource->id >>.
251
252There is no difference between B<resources>() and
253B<list_resources>().
254
255=over
256
257=item $self->B<tokens>
258
259=item $self->B<list_tokens>
260
261Official documentation: L<https://developer.scaleway.com/#tokens-tokens-get>.
262
263=item $self->B<organizations>
264
265=item $self->B<list_organizations>
266
267Official documentation: L<https://developer.scaleway.com/#organizations-organizations>.
268
269=item $self->B<servers>
270
271=item $self->B<list_servers>
272
273Official documentation: L<https://developer.scaleway.com/#servers-servers-get>.
274
275=item $self->B<volumes>
276
277=item $self->B<list_volumes>
278
279Official documentation: L<https://developer.scaleway.com/#volumes-volumes-get>.
280
281=item $self->B<snapshots>
282
283=item $self->B<list_snapshots>
284
285Official documentation: L<https://developer.scaleway.com/#snapshots-snapshots-get>.
286
287=item $self->B<images>
288
289=item $self->B<list_images>
290
291Official documentation: L<https://developer.scaleway.com/#images-images-get>.
292
293=item $self->B<ips>
294
295=item $self->B<list_ips>
296
297Official documentation: L<https://developer.scaleway.com/#ips-ips-get>.
298
299=item $self->B<security_groups>
300
301=item $self->B<list_security_groups>
302
303Official documentation: L<https://developer.scaleway.com/#security-groups-security-groups-get>.
304
305=item $self->B<security_group_rules>(I<$group_id>)
306
307=item $self->B<list_security_group_rules>(I<$group_id>)
308
309Official documentation: L<https://developer.scaleway.com/#security-groups-manage-rules-get>.
310
311=back
312
313=head2 Retrieving resources
314
315These methods take the id of a resource and return the resource as a
316blessed hashref as described in the previous section.
317
318There is no difference between B<resource>(I<$id>) and
319B<get_resource>(I<$id>).
320
321=over
322
323=item $self->B<token>(I<$id>)
324
325=item $self->B<get_token>(I<$id>)
326
327Official documentation: L<https://developer.scaleway.com/#tokens-token-get>.
328
329=item $self->B<user>(I<$id>)
330
331=item $self->B<get_user>(I<$id>)
332
333Official documentation: L<https://developer.scaleway.com/#users-user>.
334
335=item $self->B<server>(I<$id>)
336
337=item $self->B<get_server>(I<$id>)
338
339Official documentation: L<https://developer.scaleway.com/#servers-server-get>.
340
341=item $self->B<volume>(I<$id>)
342
343=item $self->B<get_volume>(I<$id>)
344
345Official documentation: L<https://developer.scaleway.com/#volumes-volume-get>.
346
347=item $self->B<snapshot>(I<$id>)
348
349=item $self->B<get_snapshot>(I<$id>)
350
351Official documentation: L<https://developer.scaleway.com/#snapshots-snapshot-get>.
352
353=item $self->B<image>(I<$id>)
354
355=item $self->B<get_image>(I<$id>)
356
357Official documentation: L<https://developer.scaleway.com/#images-operation-on-a-single-image-get>.
358
359=item $self->B<ip>(I<$id>)
360
361=item $self->B<get_ip>(I<$id>)
362
363Official documentation: L<https://developer.scaleway.com/#ips-ip-get>.
364
365=item $self->B<security_group>(I<$id>)
366
367=item $self->B<get_security_group>(I<$id>)
368
369Official documentation: L<https://developer.scaleway.com/#security-groups-operation-on-a-security-groups-get>.
370
371=item $self->B<security_group_rule>(I<$group_id>, I<$rule_id>)
372
373=item $self->B<get_security_group_rule>(I<$group_id>, I<$rule_id>)
374
375Official documentation: L<https://developer.scaleway.com/#security-groups-operation-on-a-security-rule-get>.
376
377=back
378
379=head2 Deleting resources
380
381These methods take the id of a resource and delete it. They do not
382return anything.
383
384=over
385
386=item $self->B<delete_token>(I<$id>)
387
388Official documentation: L<https://developer.scaleway.com/#tokens-token-delete>.
389
390=item $self->B<delete_server>(I<$id>)
391
392Official documentation: L<https://developer.scaleway.com/#servers-server-delete>.
393
394=item $self->B<delete_volume>(I<$id>)
395
396Official documentation: L<https://developer.scaleway.com/#volumes-volume-delete>.
397
398=item $self->B<delete_snapshot>(I<$id>)
399
400Official documentation: L<https://developer.scaleway.com/#snapshots-snapshot-delete>.
401
402=item $self->B<delete_image>(I<$id>)
403
404Official documentation: L<https://developer.scaleway.com/#images-operation-on-a-single-image-delete>.
405
406=item $self->B<delete_ip>(I<$id>)
407
408Official documentation: L<https://developer.scaleway.com/#ips-ip-delete>.
409
410=item $self->B<delete_security_group>(I<$id>)
411
412Official documentation: L<https://developer.scaleway.com/#security-groups-operation-on-a-security-groups-delete>.
413
414=item $self->B<delete_security_group_rule>(I<$group_id>, I<$rule_id>)
415
416Official documentation: L<https://developer.scaleway.com/#security-groups-operation-on-a-security-rule-delete>.
417
418=back
419
420=head2 Modifying resources
421
422These methods take a hashref representing a resource that already
423exists and update it. The value of C<< $resource->{id} >> is used for
424identifying this resource on the remote end. Both blessed and
425unblessed hashrefs are accepted. The updated resource is returned as a
426blessed hashref as described in L</"Listing resources">.
427
428=over
429
430=item $self->B<update_server>(I<$resource>)
431
432Official documentation: L<https://developer.scaleway.com/#servers-server-put>.
433
434=item $self->B<update_snapshot>(I<$resource>)
435
436Official documentation: L<https://developer.scaleway.com/#snapshots-snapshot-put>.
437
438=item $self->B<update_image>(I<$resource>)
439
440Official documentation: L<https://developer.scaleway.com/#images-operation-on-a-single-image-put>.
441
442=item $self->B<update_ip>(I<$resource>)
443
444Official documentation: L<https://developer.scaleway.com/#ips-ip-put>.
445
446=item $self->B<update_security_group>(I<$resource>)
447
448Official documentation: L<https://developer.scaleway.com/#security-groups-operation-on-a-security-groups-put>.
449
450=item $self->B<update_security_group_rule>(I<$group_id>, I<$resource>)
451
452Official documentation: L<https://developer.scaleway.com/#security-groups-operation-on-a-security-rule-put>.
453
454=back
455
456=head2 Creating resources
457
458These methods take either a hash that is passed directly to the API or
459a method-specific list of positional parameters. They create a new
460resource and return it as a blessed hashref as described in
461L</"Listing resources">.
462
463When using positional parameters, you can pass a resource in blessed
464hashref format where a resource ID is expected. The function will call
465C<< ->id >> on the resouce automatically.
466
467Most of these methods require an organization ID. You can obtain it
468with the B<organizations> method described above.
469
470=over
471
472=item $self->B<create_token>(I<\%data>)
473
474=item $self->B<create_token>(I<$email>, I<$password>, [I<$expires>])
475
476Authenticates a user against their username and password and returns
477an authentication token. If I<$expires> (default: false) is true, the
478token will expire.
479
480This method is called internally by the two-argument constructor.
481
482Official documentation: L<https://developer.scaleway.com/#tokens-tokens-get>.
483
484=item $self->B<create_server>(I<\%data>)
485
486=item $self->B<create_server>(I<$name>, I<$organization>, I<$image>, I<$volumes>, [I<$tags>])
487
488Creates and returns a new server.
489
490I<$name> is the server name. I<$organization> is the organization ID.
491I<$image> is the image ID. I<$volumes> is a "sparse array" (hashref
492from indexes to volumes, indexed from 1) of volumes. I<$tags> is an
493optional arrayref of tags.
494
495Note that the volumes must be unblessed hashrefs. If I<$vol> is a
496volume, you can use this idiom: C<< $volumes = {1 => {%$vol}} >>.
497
498Official documentation: L<https://developer.scaleway.com/#servers-servers-get>.
499
500=item $self->B<create_volume>(I<\%data>)
501
502=item $self->B<create_volume>(I<$name>, I<$organization>, I<$volume_type>, I<$size>)
503
504Creates and returns a new volume. I<$volume_type> currently must be
505C<l_ssd>. I<$size> is the size in bytes.
506
507Official documentation: L<https://developer.scaleway.com/#volumes-volumes-get>.
508
509=item $self->B<create_snapshot>(I<\%data>)
510
511=item $self->B<create_snapshot>(I<$name>, I<$organization>, I<$volume_id>)
512
513Creates and returns a snapshot of the volume I<$volume_id>.
514
515Official documentation: L<https://developer.scaleway.com/#snapshots-snapshots-get>.
516
517=item $self->B<create_image>(I<\%data>)
518
519=item $self->B<create_image>(I<$name>, I<$organization>, I<$root_volume>, I<$arch>)
520
521Creates and returns an image from the volume I<$root_volume>. I<$arch>
522is the architecture of the image (currently must be C<"arm">).
523
524Official documentation: L<https://developer.scaleway.com/#images-images-get>.
525
526=item $self->B<create_ip>(I<\%data>)
527
528=item $self->B<create_ip>(I<$organization>)
529
530Official documentation: L<https://developer.scaleway.com/#ips-ips-get>.
531
532=item $self->B<create_security_group>(I<\%data>)
533
534=item $self->B<create_security_group>(I<$name>, I<$organization>, I<$description>)
535
536Official documentation: L<https://developer.scaleway.com/#security-groups-security-groups-get>.
537
538=item $self->B<create_security_group_rule>(I<$group_id>)
539
540=item $self->B<create_security_group_rule>(I<$group_id>, I<$organization>, I<$action>, I<$direction>, I<$ip_range>, I<$protocol>, [<$dest_port_from>])
541
542
543Official documentation: L<https://developer.scaleway.com/#security-groups-manage-rules-get>.
544
545=back
546
547=head2 Miscellaneous methods
548
549These are methods that don't fit any previous category. Any use of
550"blessed hashref" refers to the concept described in L</"Listing
551resources">. Wherever a resource ID is expected, you can instead pass
552a resource as a blessed hashref and the method will call C<< ->id >>
553on it for you.
554
555=over
556
557=item $self->B<server_actions>(I<$server_id>)
558
559=item $self->B<list_server_actions>(I<$server_id>)
560
561Returns a list of strings representing possible actions you can
562perform on the given server. Example actions are powering on/off a
563server or rebooting it.
564
565Official documentation: L<https://developer.scaleway.com/#servers-actions-get>
566
567=item $self->B<perform_server_action>(I<$server_id>, I<$action>)
568
569Performs an action on a server. I<$action> is one of the strings
570returned by B<server_actions>. The function returns a blessed hashref
571with information about the task.
572
573This is not very useful, as this module does not currently offer any
574function for tracking tasks.
575
576Official documentation: L<https://developer.scaleway.com/#servers-actions-post>
577
578=item $self->B<refresh_token>(I<$token_id>)
579
580This method takes the ID of an expirable token, extends its expiration
581date by 30 minutes, and returns the new token as a blessed hashref.
582
583Official documentation: L<https://developer.scaleway.com/#tokens-token-patch>
584
585=item $self->B<server_metadata>
586
587This method can only be called from a Scaleway server. It returns
588information about the server as a blessed hashref.
589
590Official documentation: L<https://developer.scaleway.com/#metadata-c1-server-metadata>
591
592=back
593
594=head1 SEE ALSO
595
596L<https://developer.scaleway.com/>
597
598=head1 AUTHOR
599
600Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
601
602=head1 COPYRIGHT AND LICENSE
603
604Copyright (C) 2015 by Marius Gavrilescu
605
606This library is free software; you can redistribute it and/or modify
607it under the same terms as Perl itself, either Perl version 5.20.2 or,
608at your option, any later version of Perl 5 you may have available.
609
610
611=cut
This page took 0.072684 seconds and 4 git commands to generate.