forked from linode/linode_api4-python
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathlinode_client.py
More file actions
1912 lines (1523 loc) · 71.1 KB
/
Copy pathlinode_client.py
File metadata and controls
1912 lines (1523 loc) · 71.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
from __future__ import annotations
import json
import logging
import os
import time
from datetime import datetime
from typing import Tuple, BinaryIO
import pkg_resources
import requests
from linode_api4.errors import ApiError, UnexpectedResponseError
from linode_api4.objects import *
from linode_api4.objects.filtering import Filter
from .common import SSH_KEY_TYPES, load_and_validate_keys
from .paginated_list import PaginatedList
from .util import drop_null_keys
package_version = pkg_resources.require("linode_api4")[0].version
logger = logging.getLogger(__name__)
class Group:
def __init__(self, client: LinodeClient):
self.client = client
class LinodeGroup(Group):
"""
Encapsulates Linode-related methods of the :any:`LinodeClient`. This
should not be instantiated on its own, but should instead be used through
an instance of :any:`LinodeClient`::
client = LinodeClient(token)
instances = client.linode.instances() # use the LinodeGroup
This group contains all features beneath the `/linode` group in the API v4.
"""
def types(self, *filters):
"""
Returns a list of Linode Instance types. These may be used to create
or resize Linodes, or simply referenced on their own. Types can be
filtered to return specific types, for example::
standard_types = client.linode.types(Type.class == "standard")
:param filters: Any number of filters to apply to the query.
:returns: A list of types that match the query.
:rtype: PaginatedList of Type
"""
return self.client._get_and_filter(Type, *filters)
def instances(self, *filters):
"""
Returns a list of Linode Instances on your account. You may filter
this query to return only Linodes that match specific criteria::
prod_linodes = client.linode.instances(Instance.group == "prod")
:param filters: Any number of filters to apply to this query.
:returns: A list of Instances that matched the query.
:rtype: PaginatedList of Instance
"""
return self.client._get_and_filter(Instance, *filters)
def stackscripts(self, *filters, **kwargs):
"""
Returns a list of :any:`StackScripts<StackScript>`, both public and
private. You may filter this query to return only
:any:`StackScripts<StackScript>` that match certain criteria. You may
also request only your own private :any:`StackScripts<StackScript>`::
my_stackscripts = client.linode.stackscripts(mine_only=True)
:param filters: Any number of filters to apply to this query.
:param mine_only: If True, returns only private StackScripts
:type mine_only: bool
:returns: A list of StackScripts matching the query.
:rtype: PaginatedList of StackScript
"""
# python2 can't handle *args and a single keyword argument, so this is a workaround
if 'mine_only' in kwargs:
if kwargs['mine_only']:
new_filter = Filter({"mine":True})
if filters:
filters = list(filters)
filters[0] = filters[0] & new_filter
else:
filters = [new_filter]
del kwargs['mine_only']
if kwargs:
raise TypeError("stackscripts() got unexpected keyword argument '{}'".format(kwargs.popitem()[0]))
return self.client._get_and_filter(StackScript, *filters)
def kernels(self, *filters):
"""
Returns a list of available :any:`Kernels<Kernel>`. Kernels are used
when creating or updating :any:`LinodeConfigs,LinodeConfig>`.
:param filters: Any number of filters to apply to this query.
:returns: A list of available kernels that match the query.
:rtype: PaginatedList of Kernel
"""
return self.client._get_and_filter(Kernel, *filters)
# create things
def instance_create(self, ltype, region, image=None,
authorized_keys=None, **kwargs):
"""
Creates a new Linode Instance. This function has several modes of operation:
**Create an Instance from an Image**
To create an Instance from an :any:`Image`, call `instance_create` with
a :any:`Type`, a :any:`Region`, and an :any:`Image`. All three of
these fields may be provided as either the ID or the appropriate object.
In this mode, a root password will be generated and returned with the
new Instance object. For example::
new_linode, password = client.linode.instance_create(
"g6-standard-2",
"us-east",
image="linode/debian9")
ltype = client.linode.types().first()
region = client.regions().first()
image = client.images().first()
another_linode, password = client.linode.instance_create(
ltype,
region,
image=image)
**Create an Instance from StackScript**
When creating an Instance from a :any:`StackScript`, an :any:`Image` that
the StackScript support must be provided.. You must also provide any
required StackScript data for the script's User Defined Fields.. For
example, if deploying `StackScript 10079`_ (which deploys a new Instance
with a user created from keys on `github`_::
stackscript = StackScript(client, 10079)
new_linode, password = client.linode.instance_create(
"g6-standard-2",
"us-east",
image="linode/debian9",
stackscript=stackscript,
stackscript_data={"gh_username": "example"})
In the above example, "gh_username" is the name of a User Defined Field
in the chosen StackScript. For more information on StackScripts, see
the `StackScript guide`_.
.. _`StackScript 10079`: https://www.linode.com/stackscripts/view/10079
.. _`github`: https://github.com
.. _`StackScript guide`: https://www.linode.com/docs/platform/stackscripts/
**Create an Instance from a Backup**
To create a new Instance by restoring a :any:`Backup` to it, provide a
:any:`Type`, a :any:`Region`, and the :any:`Backup` to restore. You
may provide either IDs or objects for all of these fields::
existing_linode = Instance(client, 123)
snapshot = existing_linode.available_backups.snapshot.current
new_linode = client.linode.instance_create(
"g6-standard-2",
"us-east",
backup=snapshot)
**Create an empty Instance**
If you want to create an empty Instance that you will configure manually,
simply call `instance_create` with a :any:`Type` and a :any:`Region`::
empty_linode = client.linode.instance_create("g6-standard-2", "us-east")
When created this way, the Instance will not be booted and cannot boot
successfully until disks and configs are created, or it is otherwise
configured.
:param ltype: The Instance Type we are creating
:type ltype: str or Type
:param region: The Region in which we are creating the Instance
:type region: str or Region
:param image: The Image to deploy to this Instance. If this is provided
and no root_pass is given, a password will be generated
and returned along with the new Instance.
:type image: str or Image
:param stackscript: The StackScript to deploy to the new Instance. If
provided, "image" is required and must be compatible
with the chosen StackScript.
:type stackscript: int or StackScript
:param stackscript_data: Values for the User Defined Fields defined in
the chosen StackScript. Does nothing if
StackScript is not provided.
:type stackscript_data: dict
:param backup: The Backup to restore to the new Instance. May not be
provided if "image" is given.
:type backup: int of Backup
:param authorized_keys: The ssh public keys to install in the linode's
/root/.ssh/authorized_keys file. Each entry may
be a single key, or a path to a file containing
the key.
:type authorized_keys: list or str
:param label: The display label for the new Instance
:type label: str
:param group: The display group for the new Instance
:type group: str
:param booted: Whether the new Instance should be booted. This will
default to True if the Instance is deployed from an Image
or Backup.
:type booted: bool
:param tags: A list of tags to apply to the new instance. If any of the
tags included do not exist, they will be created as part of
this operation.
:type tags: list[str]
:param private_ip: Whether the new Instance should have private networking
enabled and assigned a private IPv4 address.
:type private_ip: bool
:returns: A new Instance object, or a tuple containing the new Instance and
the generated password.
:rtype: Instance or tuple(Instance, str)
:raises ApiError: If contacting the API fails
:raises UnexpectedResponseError: If the API response is somehow malformed.
This usually indicates that you are using
an outdated library.
"""
ret_pass = None
if image and not 'root_pass' in kwargs:
ret_pass = Instance.generate_root_password()
kwargs['root_pass'] = ret_pass
authorized_keys = load_and_validate_keys(authorized_keys)
if "stackscript" in kwargs:
# translate stackscripts
kwargs["stackscript_id"] = (kwargs["stackscript"].id if issubclass(type(kwargs["stackscript"]), Base)
else kwargs["stackscript"])
del kwargs["stackscript"]
if "backup" in kwargs:
# translate backups
kwargs["backup_id"] = (kwargs["backup"].id if issubclass(type(kwargs["backup"]), Base)
else kwargs["backup"])
del kwargs["backup"]
params = {
'type': ltype.id if issubclass(type(ltype), Base) else ltype,
'region': region.id if issubclass(type(region), Base) else region,
'image': (image.id if issubclass(type(image), Base) else image) if image else None,
'authorized_keys': authorized_keys,
}
params.update(kwargs)
result = self.client.post('/linode/instances', data=params)
if not 'id' in result:
raise UnexpectedResponseError('Unexpected response when creating linode!', json=result)
l = Instance(self.client, result['id'], result)
if not ret_pass:
return l
return l, ret_pass
def stackscript_create(self, label, script, images, desc=None, public=False, **kwargs):
"""
Creates a new :any:`StackScript` on your account.
:param label: The label for this StackScript.
:type label: str
:param script: The script to run when an :any:`Instance` is deployed with
this StackScript. Must begin with a shebang (#!).
:type script: str
:param images: A list of :any:`Images<Image>` that this StackScript
supports. Instances will not be deployed from this
StackScript unless deployed from one of these Images.
:type images: list of Image
:param desc: A description for this StackScript.
:type desc: str
:param public: Whether this StackScript is public. Defaults to False.
Once a StackScript is made public, it may not be set
back to private.
:type public: bool
:returns: The new StackScript
:rtype: StackScript
"""
image_list = None
if type(images) is list or type(images) is PaginatedList:
image_list = [d.id if issubclass(type(d), Base) else d for d in images ]
elif type(images) is Image:
image_list = [images.id]
elif type(images) is str:
image_list = [images]
else:
raise ValueError('images must be a list of Images or a single Image')
script_body = script
if not script.startswith("#!"):
# it doesn't look like a stackscript body, let's see if it's a file
if os.path.isfile(script):
with open(script) as f:
script_body = f.read()
else:
raise ValueError("script must be the script text or a path to a file")
params = {
"label": label,
"images": image_list,
"is_public": public,
"script": script_body,
"description": desc if desc else '',
}
params.update(kwargs)
result = self.client.post('/linode/stackscripts', data=params)
if not 'id' in result:
raise UnexpectedResponseError('Unexpected response when creating StackScript!', json=result)
s = StackScript(self.client, result['id'], result)
return s
class ProfileGroup(Group):
"""
Collections related to your user.
"""
def __call__(self):
"""
Retrieve the acting user's Profile, containing information about the
current user such as their email address, username, and uid. This is
intended to be called off of a :any:`LinodeClient` object, like this::
profile = client.profile()
:returns: The acting user's profile.
:rtype: Profile
"""
result = self.client.get('/profile')
if not 'username' in result:
raise UnexpectedResponseError('Unexpected response when getting profile!', json=result)
p = Profile(self.client, result['username'], result)
return p
def tokens(self, *filters):
"""
Returns the Person Access Tokens active for this user
"""
return self.client._get_and_filter(PersonalAccessToken, *filters)
def token_create(self, label=None, expiry=None, scopes=None, **kwargs):
"""
Creates and returns a new Personal Access Token
"""
if label:
kwargs['label'] = label
if expiry:
if isinstance(expiry, datetime):
expiry = datetime.strftime(expiry, "%Y-%m-%dT%H:%M:%S")
kwargs['expiry'] = expiry
if scopes:
kwargs['scopes'] = scopes
result = self.client.post('/profile/tokens', data=kwargs)
if not 'id' in result:
raise UnexpectedResponseError('Unexpected response when creating Personal Access '
'Token!', json=result)
token = PersonalAccessToken(self.client, result['id'], result)
return token
def apps(self, *filters):
"""
Returns the Authorized Applications for this user
"""
return self.client._get_and_filter(AuthorizedApp, *filters)
def ssh_keys(self, *filters):
"""
Returns the SSH Public Keys uploaded to your profile
"""
return self.client._get_and_filter(SSHKey, *filters)
def ssh_key_upload(self, key, label):
"""
Uploads a new SSH Public Key to your profile This key can be used in
later Linode deployments.
:param key: The ssh key, or a path to the ssh key. If a path is provided,
the file at the path must exist and be readable or an exception
will be thrown.
:type key: str
:param label: The name to give this key. This is purely aesthetic.
:type label: str
:returns: The newly uploaded SSH Key
:rtype: SSHKey
:raises ValueError: If the key provided does not appear to be valid, and
does not appear to be a path to a valid key.
"""
if not key.startswith(SSH_KEY_TYPES):
# this might be a file path - look for it
path = os.path.expanduser(key)
if os.path.isfile(path):
with open(path) as f:
key = f.read().strip()
if not key.startswith(SSH_KEY_TYPES):
raise ValueError('Invalid SSH Public Key')
params = {
'ssh_key': key,
'label': label,
}
result = self.client.post('/profile/sshkeys', data=params)
if not 'id' in result:
raise UnexpectedResponseError('Unexpected response when uploading SSH Key!',
json=result)
ssh_key = SSHKey(self.client, result['id'], result)
return ssh_key
class LKEGroup(Group):
"""
Encapsulates LKE-related methods of the :any:`LinodeClient`. This
should not be instantiated on its own, but should instead be used through
an instance of :any:`LinodeClient`::
client = LinodeClient(token)
instances = client.lke.clusters() # use the LKEGroup
This group contains all features beneath the `/lke` group in the API v4.
"""
def versions(self, *filters):
"""
Returns a :any:`PaginatedList` of :any:`KubeVersion` objects that can be
used when creating an LKE Cluster.
:param filters: Any number of filters to apply to the query.
:returns: A Paginated List of kube versions that match the query.
:rtype: PaginatedList of KubeVersion
"""
return self.client._get_and_filter(KubeVersion, *filters)
def clusters(self, *filters):
"""
Returns a :any:`PaginagtedList` of :any:`LKECluster` objects that belong
to this account.
:param filters: Any number of filters to apply to the query.
:returns: A Paginated List of LKE clusters that match the query.
:rtype: PaginatedList of LKECluster
"""
return self.client._get_and_filter(LKECluster, *filters)
def cluster_create(self, region, label, node_pools, kube_version, **kwargs):
"""
Creates an :any:`LKECluster` on this account in the given region, with
the given label, and with node pools as described. For example::
client = LinodeClient(TOKEN)
# look up Region and Types to use. In this example I'm just using
# the first ones returned.
target_region = client.regions().first()
node_type = client.linode.types()[0]
node_type_2 = client.linode.types()[1]
kube_version = client.lke.versions()[0]
new_cluster = client.lke.cluster_create(
target_region,
"example-cluster",
[client.lke.node_pool(node_type, 3), client.lke.node_pool(node_type_2, 3)],
kube_version
)
:param region: The Region to create this LKE Cluster in.
:type region: Region or str
:param label: The label for the new LKE Cluster.
:type label: str
:param node_pools: The Node Pools to create.
:type node_pools: one or a list of dicts containing keys "type" and "count". See
:any:`node_pool` for a convenient way to create correctly-
formatted dicts.
:param kube_version: The version of Kubernetes to use
:type kube_version: KubeVersion or str
:param kwargs: Any other arguments to pass along to the API. See the API
docs for possible values.
:returns: The new LKE Cluster
:rtype: LKECluster
"""
pools = []
if not isinstance(node_pools, list):
node_pools = [node_pools]
for c in node_pools:
if isinstance(c, dict):
new_pool = {
"type": c["type"].id
if "type" in c and issubclass(type(c["type"]), Base)
else c.get("type"),
"count": c.get("count"),
}
pools += [new_pool]
params = {
"label": label,
"region": region.id if issubclass(type(region), Base) else region,
"node_pools": pools,
"k8s_version": kube_version.id
if issubclass(type(kube_version), Base)
else kube_version,
}
params.update(kwargs)
result = self.client.post('/lke/clusters', data=params)
if 'id' not in result:
raise UnexpectedResponseError('Unexpected response when creating LKE cluster!', json=result)
return LKECluster(self.client, result['id'], result)
def node_pool(self, node_type, node_count):
"""
Returns a dict that is suitable for passing into the `node_pools` array
of :any:`cluster_create`. This is a convenience method, and need not be
used to create Node Pools. For proper usage, see the docs for :any:`cluster_create`.
:param node_type: The type of node to create in this node pool.
:type node_type: Type or str
:param node_count: The number of nodes to create in this node pool.
:type node_count: int
:returns: A dict describing the desired node pool.
:rtype: dict
"""
return {
"type": node_type,
"count": node_count,
}
class LongviewGroup(Group):
def clients(self, *filters):
"""
Requests and returns a paginated list of LongviewClients on your
account.
"""
return self.client._get_and_filter(LongviewClient, *filters)
def client_create(self, label=None):
"""
Creates a new LongviewClient, optionally with a given label.
:param label: The label for the new client. If None, a default label based
on the new client's ID will be used.
:returns: A new LongviewClient
:raises ApiError: If a non-200 status code is returned
:raises UnexpectedResponseError: If the returned data from the api does
not look as expected.
"""
result = self.client.post('/longview/clients', data={
"label": label
})
if not 'id' in result:
raise UnexpectedResponseError('Unexpected response when creating Longivew '
'Client!', json=result)
c = LongviewClient(self.client, result['id'], result)
return c
def subscriptions(self, *filters):
"""
Requests and returns a paginated list of LongviewSubscriptions available
"""
return self.client._get_and_filter(LongviewSubscription, *filters)
class AccountGroup(Group):
def __call__(self):
"""
Retrieves information about the acting user's account, such as billing
information. This is intended to be called off of the :any:`LinodeClient`
class, like this::
account = client.account()
:returns: Returns the acting user's account information.
:rtype: Account
"""
result = self.client.get('/account')
if not 'email' in result:
raise UnexpectedResponseError('Unexpected response when getting account!', json=result)
return Account(self.client, result['email'], result)
def events(self, *filters):
return self.client._get_and_filter(Event, *filters)
def events_mark_seen(self, event):
"""
Marks event as the last event we have seen. If event is an int, it is treated
as an event_id, otherwise it should be an event object whose id will be used.
"""
last_seen = event if isinstance(event, int) else event.id
self.client.post('{}/seen'.format(Event.api_endpoint), model=Event(self.client, last_seen))
def settings(self):
"""
Resturns the account settings data for this acocunt. This is not a
listing endpoint.
"""
result = self.client.get('/account/settings')
if not 'managed' in result:
raise UnexpectedResponseError('Unexpected response when getting account settings!',
json=result)
s = AccountSettings(self.client, result['managed'], result)
return s
def invoices(self):
"""
Returns Invoices issued to this account
"""
return self.client._get_and_filter(Invoice)
def payments(self):
"""
Returns a list of Payments made to this account
"""
return self.client._get_and_filter(Payment)
def oauth_clients(self, *filters):
"""
Returns the OAuth Clients associated to this account
"""
return self.client._get_and_filter(OAuthClient, *filters)
def oauth_client_create(self, name, redirect_uri, **kwargs):
"""
Make a new OAuth Client and return it
"""
params = {
"label": name,
"redirect_uri": redirect_uri,
}
params.update(kwargs)
result = self.client.post('/account/oauth-clients', data=params)
if not 'id' in result:
raise UnexpectedResponseError('Unexpected response when creating OAuth Client!',
json=result)
c = OAuthClient(self.client, result['id'], result)
return c
def users(self, *filters):
"""
Returns a list of users on this account
"""
return self.client._get_and_filter(User, *filters)
def transfer(self):
"""
Returns a MappedObject containing the account's transfer pool data
"""
result = self.client.get('/account/transfer')
if not 'used' in result:
raise UnexpectedResponseError('Unexpected response when getting Transfer Pool!')
return MappedObject(**result)
def user_create(self, email, username, restricted=True):
"""
Creates a new user on your account. If you create an unrestricted user,
they will immediately be able to access everything on your account. If
you create a restricted user, you must grant them access to parts of your
account that you want to allow them to manage (see :any:`User.grants` for
details).
The new user will receive an email inviting them to set up their password.
This must be completed before they can log in.
:param email: The new user's email address. This is used to finish setting
up their user account.
:type email: str
:param username: The new user's unique username. They will use this username
to log in.
:type username: str
:param restricted: If True, the new user must be granted access to parts of
the account before they can do anything. If False, the
new user will immediately be able to manage the entire
account. Defaults to True.
:type restricted: True
:returns The new User.
:rtype: User
"""
params = {
"email": email,
"username": username,
"restricted": restricted,
}
result = self.client.post('/account/users', data=params)
if not all([c in result for c in ('email', 'restricted', 'username')]): # pylint: disable=use-a-generator
raise UnexpectedResponseError('Unexpected response when creating user!', json=result)
u = User(self.client, result['username'], result)
return u
class NetworkingGroup(Group):
def firewalls(self, *filters):
"""
.. note:: This endpoint is in beta. This will only function if base_url is set to `https://api.linode.com/v4beta`.
Retrieves the Firewalls your user has access to.
:param filters: Any number of filters to apply to this query.
:returns: A list of Firewalls the acting user can access.
:rtype: PaginatedList of Firewall
"""
return self.client._get_and_filter(Firewall, *filters)
def firewall_create(self, label, rules, **kwargs):
"""
.. note:: This endpoint is in beta. This will only function if base_url is set to `https://api.linode.com/v4beta`.
Creates a new Firewall, either in the given Region or
attached to the given Instance.
:param label: The label for the new Firewall.
:type label: str
:param rules: The rules to apply to the new Firewall. For more information on Firewall rules, see our `Firewalls Documentation`_.
:type rules: dict
:returns: The new Firewall.
:rtype: Firewall
Example usage::
rules = {
'outbound': [
{
'action': 'ACCEPT',
'addresses': {
'ipv4': [
'0.0.0.0/0'
],
'ipv6': [
"ff00::/8"
]
},
'description': 'Allow HTTP out.',
'label': 'allow-http-out',
'ports': '80',
'protocol': 'TCP'
}
],
'outbound_policy': 'DROP',
'inbound': [],
'inbound_policy': 'DROP'
}
firewall = client.networking.firewall_create('my-firewall', rules)
.. _Firewalls Documentation: https://www.linode.com/docs/api/networking/#firewall-create__request-body-schema
"""
params = {
'label': label,
'rules': rules,
}
params.update(kwargs)
result = self.client.post('/networking/firewalls', data=params)
if not 'id' in result:
raise UnexpectedResponseError('Unexpected response when creating Firewall!', json=result)
f = Firewall(self.client, result['id'], result)
return f
def ips(self, *filters):
return self.client._get_and_filter(IPAddress, *filters)
def ipv6_ranges(self, *filters):
return self.client._get_and_filter(IPv6Range, *filters)
def ipv6_pools(self, *filters):
return self.client._get_and_filter(IPv6Pool, *filters)
def vlans(self, *filters):
"""
.. note:: This endpoint is in beta. This will only function if base_url is set to `https://api.linode.com/v4beta`.
Returns a list of VLANs on your account.
:returns: A Paginated List of VLANs on your account.
:rtype: PaginatedList of VLAN
"""
return self.client._get_and_filter(VLAN, *filters)
def ips_assign(self, region, *assignments):
"""
Redistributes :any:`IP Addressees<IPAddress>` within a single region.
This function takes a :any:`Region` and a list of assignments to make,
then requests that the assignments take place. If any :any:`Instance`
ends up without a public IP, or with more than one private IP, all of
the assignments will fail.
.. note::
This function *does not* update the local Linode Instance objects
when called. In order to see the new addresses on the local
instance objects, be sure to invalidate them with ``invalidate()``
after this completes.
Example usage::
linode1 = Instance(client, 123)
linode2 = Instance(client, 456)
# swap IPs between linodes 1 and 2
client.networking.assign_ips(linode1.region,
linode1.ips.ipv4.public[0].to(linode2),
linode2.ips.ipv4.public[0].to(linode1))
# make sure linode1 and linode2 have updated ipv4 and ips values
linode1.invalidate()
linode2.invalidate()
:param region: The Region in which the assignments should take place.
All Instances and IPAddresses involved in the assignment
must be within this region.
:type region: str or Region
:param assignments: Any number of assignments to make. See
:any:`IPAddress.to` for details on how to construct
assignments.
:type assignments: dct
"""
for a in assignments:
if not 'address' in a or not 'linode_id' in a:
raise ValueError("Invalid assignment: {}".format(a))
if isinstance(region, Region):
region = region.id
self.client.post('/networking/ipv4/assign', data={
"region": region,
"assignments": assignments,
})
def ip_allocate(self, linode, public=True):
"""
Allocates an IP to a Instance you own. Additional IPs must be requested
by opening a support ticket first.
:param linode: The Instance to allocate the new IP for.
:type linode: Instance or int
:param public: If True, allocate a public IP address. Defaults to True.
:type public: bool
:returns: The new IPAddress
:rtype: IPAddress
"""
result = self.client.post('/networking/ips/', data={
"linode_id": linode.id if isinstance(linode, Base) else linode,
"type": "ipv4",
"public": public,
})
if not 'address' in result:
raise UnexpectedResponseError('Unexpected response when adding IPv4 address!',
json=result)
ip = IPAddress(self.client, result['address'], result)
return ip
def ips_share(self, linode, *ips):
"""
Shares the given list of :any:`IPAddresses<IPAddress>` with the provided
:any:`Instance`. This will enable the provided Instance to bring up the
shared IP Addresses even though it does not own them.
:param linode: The Instance to share the IPAddresses with. This Instance
will be able to bring up the given addresses.
:type: linode: int or Instance
:param ips: Any number of IPAddresses to share to the Instance.
:type ips: str or IPAddress
"""
if not isinstance(linode, Instance):
# make this an object
linode = Instance(self.client, linode)
params = []
for ip in ips:
if isinstance(ip, str):
params.append(ip)
elif isinstance(ip, IPAddress):
params.append(ip.address)
else:
params.append(str(ip)) # and hope that works
params = {
"ips": params
}
self.client.post('{}/networking/ipv4/share'.format(Instance.api_endpoint),
model=linode, data=params)
linode.invalidate() # clear the Instance's shared IPs
class SupportGroup(Group):
def tickets(self, *filters):
return self.client._get_and_filter(SupportTicket, *filters)
def ticket_open(self, summary, description, regarding=None):
"""
"""
params = {
"summary": summary,
"description": description,
}
if regarding:
if isinstance(regarding, Instance):
params['linode_id'] = regarding.id
elif isinstance(regarding, Domain):
params['domain_id'] = regarding.id
elif isinstance(regarding, NodeBalancer):
params['nodebalancer_id'] = regarding.id
elif isinstance(regarding, Volume):
params['volume_id'] = regarding.id
else:
raise ValueError('Cannot open ticket regarding type {}!'.format(type(regarding)))
result = self.client.post('/support/tickets', data=params)
if not 'id' in result:
raise UnexpectedResponseError('Unexpected response when creating ticket!',
json=result)
t = SupportTicket(self.client, result['id'], result)
return t
class ObjectStorageGroup(Group):
"""
This group encapsulates all endpoints under /object-storage, including viewing
available clusters and managing keys.
"""
def clusters(self, *filters):
"""
Returns a list of available Object Storage Clusters. You may filter
this query to return only Clusters that are available in a specific region::
us_east_clusters = client.object_storage.clusters(ObjectStorageCluster.region == "us-east")
:param filters: Any number of filters to apply to this query.
:returns: A list of Object Storage Clusters that matched the query.
:rtype: PaginatedList of ObjectStorageCluster
"""
return self.client._get_and_filter(ObjectStorageCluster, *filters)
def keys(self, *filters):