Linode Client

The LinodeClient is responsible for managing your connection to the API using your token. A LinodeClient is required for all connections to the API, and a reference to one is required by every model. A LinodeClient is created with a token, either an OAuth Token from the OAuth Exchange (see oauth for more information) or a Personal Access Token. See our getting_started guide for more information:

from linode_api4 import LinodeClient

token = "api-token" # your token goes here

client = LinodeClient(token)

Grouping

The LinodeClient class is divided into groups following the API’s overall design - some methods and functions are accessible only through members of the LinodeClient class:

# access an ungrouped member
client.regions() # /regions

# access a grouped member - note the URL matches the grouping
client.linode.instances() # /linode/instances

The LinodeClient itself holds top-level collections of the API, while anything that exists under a group in the API belongs to a member of the client.

LinodeClient class

class linode_api4.LinodeClient(token, base_url='https://api.linode.com/v4', user_agent=None)[source]
__init__(token, base_url='https://api.linode.com/v4', user_agent=None)[source]

The main interface to the Linode API.

Parameters:
  • token (str) – The authentication token to use for communication with the API. Can be either a Personal Access Token or an OAuth Token.
  • base_url (str) – The base URL for API requests. Generally, you shouldn’t change this.
  • user_agent (str) – What to append to the User Agent of all requests made by this client. Setting this allows Linode’s internal monitoring applications to track the usage of your application. Setting this is not necessary, but some applications may desire this behavior.
account = None

Access methods related to your account - see AccountGroup for more information

domain_create(domain, master=True, **kwargs)[source]

Registers a new Domain on the acting user’s account. Make sure to point your registrar to Linode’s nameservers so that Linode’s DNS manager will correctly serve your domain.

Parameters:
  • domain (str) – The domain to register to Linode’s DNS manager.
  • master (bool) – Whether this is a master (defaults to true)
Returns:

The new Domain object.

Return type:

Domain

domains(*filters)[source]

Retrieves all of the Domains the acting user has access to.

Parameters:filters – Any number of filters to apply to this query.
Returns:A list of Domains the acting user can access.
Return type:PaginatedList of Domain
image_create(disk, label=None, description=None)[source]

Creates a new Image from a disk you own.

Parameters:
  • disk (Disk or int) – The Disk to imagize.
  • label (str) – The label for the resulting Image (defaults to the disk’s label.
  • description (str) – The description for the new Image.
Returns:

The new Image.

Return type:

Image

images(*filters)[source]

Retrieves a list of available Images, including public and private Images available to the acting user. You can filter this query to retrieve only Images relevant to a specific query, for example:

debian_images = client.images(
    Image.vendor == "debain")
Parameters:filters – Any number of filters to apply to the query.
Returns:A list of available Images.
Return type:PaginatedList of Image
linode = None

Access methods related to Linodes - see LinodeGroup for more information

load(target_type, target_id, target_parent_id=None)[source]

Constructs and immediately loads the object, circumventing the lazy-loading scheme by immediately making an API request. Does not load related objects.

For example, if you wanted to load an Instance object with ID 123, you could do this:

loaded_linode = client.load(Instance, 123)

Similarly, if you instead wanted to load a NodeBalancerConfig, you could do so like this:

loaded_nodebalancer_config = client.load(NodeBalancerConfig, 456, 432)
Parameters:
  • target_type (type) – The type of object to create.
  • target_id (int or str) – The ID of the object to create.
  • target_parent_id (int, str, or None) – The parent ID of the object to create, if applicable.
Returns:

The resulting object, fully loaded.

Return type:

target_type

Raises:

ApiError – if the requested object could not be loaded.

longview = None

Access information related to the Longview service - see LongviewGroup for more information

networking = None

Access methods related to networking on your account - see NetworkingGroup for more information

nodebalancer_create(region, **kwargs)[source]

Creates a new NodeBalancer in the given Region.

Parameters:region (Region or str) – The Region in which to create the NodeBalancer.
Returns:The new NodeBalancer
Return type:NodeBalancer
nodebalancers(*filters)[source]

Retrieves all of the NodeBalancers the acting user has access to.

Parameters:filters – Any number of filters to apply to this query.
Returns:A list of NodeBalancers the acting user can access.
Return type:PaginatedList of NodeBalancers
object_storage = None

Access methods related to Object Storage - see ObjectStorageGroup for more information

profile = None

Access methods related to your user - see ProfileGroup for more information

regions(*filters)[source]

Returns the available Regions for Linode products.

Parameters:filters – Any number of filters to apply to the query.
Returns:A list of available Regions.
Return type:PaginatedList of Region
support = None

Access methods related to support - see SupportGroup for more information

tag_create(label, instances=None, domains=None, nodebalancers=None, volumes=None, entities=[])[source]

Creates a new Tag and optionally applies it to the given entities.

Parameters:
  • label (str) – The label for the new Tag
  • entities (list of Instance, Domain, NodeBalancer, and/or Volume) – A list of objects to apply this Tag to upon creation. May only be taggable types (Linode Instances, Domains, NodeBalancers, or Volumes). These are applied in addition to any IDs specified with instances, domains, nodebalancers, or volumes, and is a convenience for sending multiple entity types without sorting them yourself.
  • instances (list of Instance or list of int) – A list of Linode Instances to apply this Tag to upon creation
  • domains (list of Domain or list of int) – A list of Domains to apply this Tag to upon creation
  • nodebalancers (list of NodeBalancer or list of int) – A list of NodeBalancers to apply this Tag to upon creation
  • volumes (list of Volumes or list of int) – A list of Volumes to apply this Tag to upon creation
Returns:

The new Tag

Return type:

Tag

tags(*filters)[source]

Retrieves the Tags on your account. This may only be attempted by unrestricted users.

Parameters:filters – Any number of filters to apply to this query.
Returns:A list of Tags on the account.
Return type:PaginatedList of Tag
volume_create(label, region=None, linode=None, size=20, **kwargs)[source]

Creates a new Block Storage Volume, either in the given Region or attached to the given Instance.

Parameters:
  • label (str) – The label for the new Volume.
  • region (Region or str) – The Region to create this Volume in. Not required if linode is provided.
  • linode (Instance or int) – The Instance to attach this Volume to. If not given, the new Volume will not be attached to anything.
  • size (int) – The size, in GB, of the new Volume. Defaults to 20.
Returns:

The new Volume.

Return type:

Volume

volumes(*filters)[source]

Retrieves the Block Storage Volumes your user has access to.

Parameters:filters – Any number of filters to apply to this query.
Returns:A list of Volumes the acting user can access.
Return type:PaginatedList of Volume

Groups

These groups are accessed off of the LinodeClient class by name. For example:

client.linode.instances()

See LinodeClient for more information on the naming of these groups, although generally they are named the same as the first word of the group.

LinodeGroup

Includes methods for managing and creating Linode Instances, as well as accessing and working with associated features.

class linode_api4.linode_client.LinodeGroup(client)[source]

Encapsulates Linode-related methods of the LinodeClient. This should not be instantiated on its own, but should instead be used through an instance of LinodeClient:

client = LinodeClient(token)
instances = client.linode.instances() # use the LinodeGroup

This group contains all features beneath the /linode group in the API v4.

instance_create(ltype, region, image=None, authorized_keys=None, **kwargs)[source]

Creates a new Linode Instance. This function has several modes of operation:

Create an Instance from an Image

To create an Instance from an Image, call instance_create with a Type, a Region, and an 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 StackScript, an 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.

Create an Instance from a Backup

To create a new Instance by restoring a Backup to it, provide a Type, a Region, and the 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 Type and a 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.

Parameters:
  • ltype (str or Type) – The Instance Type we are creating
  • region (str or Region) – The Region in which we are creating the Instance
  • image (str or 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.
  • stackscript (int or StackScript) – The StackScript to deploy to the new Instance. If provided, “image” is required and must be compatible with the chosen StackScript.
  • stackscript_data (dict) – Values for the User Defined Fields defined in the chosen StackScript. Does nothing if StackScript is not provided.
  • backup (int of Backup) – The Backup to restore to the new Instance. May not be provided if “image” is given.
  • authorized_keys (list or str) – 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.
  • label (str) – The display label for the new Instance
  • group (str) – The display group for the new Instance
  • booted (bool) – Whether the new Instance should be booted. This will default to True if the Instance is deployed from an Image or Backup.
Returns:

A new Instance object, or a tuple containing the new Instance and the generated password.

Return type:

Instance or tuple(Instance, str)

Raises:
  • ApiError – If contacting the API fails
  • UnexpectedResponseError – If the API resposne is somehow malformed. This usually indicates that you are using an outdated library.
instances(*filters)[source]

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")
Parameters:filters – Any number of filters to apply to this query.
Returns:A list of Instances that matched the query.
Return type:PaginatedList of Instance
kernels(*filters)[source]

Returns a list of available Kernels. Kernels are used when creating or updating LinodeConfigs,LinodeConfig>.

Parameters:filters – Any number of filters to apply to this query.
Returns:A list of available kernels that match the query.
Return type:PaginatedList of Kernel
stackscript_create(label, script, images, desc=None, public=False, **kwargs)[source]

Creates a new StackScript on your account.

Parameters:
  • label (str) – The label for this StackScript.
  • script (str) – The script to run when an Instance is deployed with this StackScript. Must begin with a shebang (#!).
  • images (list of Image) – A list of Images that this StackScript supports. Instances will not be deployed from this StackScript unless deployed from one of these Images.
  • desc (str) – A description for this StackScript.
  • public (bool) – Whether this StackScript is public. Defaults to False. Once a StackScript is made public, it may not be set back to private.
Returns:

The new StackScript

Return type:

StackScript

stackscripts(*filters, **kwargs)[source]

Returns a list of StackScripts, both public and private. You may filter this query to return only StackScripts that match certain criteria. You may also request only your own private StackScripts:

my_stackscripts = client.linode.stackscripts(mine_only=True)
Parameters:
  • filters – Any number of filters to apply to this query.
  • mine_only (bool) – If True, returns only private StackScripts
Returns:

A list of StackScripts matching the query.

Return type:

PaginatedList of StackScript

types(*filters)[source]

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")
Parameters:filters – Any number of filters to apply to the query.
Returns:A list of types that match the query.
Return type:PaginatedList of Type

AccountGroup

Includes methods for managing your account.

class linode_api4.linode_client.AccountGroup(client)[source]
events_mark_seen(event)[source]

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.

invoices()[source]

Returns Invoices issued to this account

oauth_client_create(name, redirect_uri, **kwargs)[source]

Make a new OAuth Client and return it

oauth_clients(*filters)[source]

Returns the OAuth Clients associated to this account

payments()[source]

Returns a list of Payments made to this account

settings()[source]

Resturns the account settings data for this acocunt. This is not a listing endpoint.

transfer()[source]

Returns a MappedObject containing the account’s transfer pool data

user_create(email, username, restricted=True)[source]

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 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.

Parameters:
  • email (str) – The new user’s email address. This is used to finish setting up their user account.
  • username (str) – The new user’s unique username. They will use this username to log in.
  • restricted (True) – 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.

:returns The new User. :rtype: User

users(*filters)[source]

Returns a list of users on this account

ProfileGroup

Includes methods for managing your user.

class linode_api4.linode_client.ProfileGroup(client)[source]

Collections related to your user.

apps(*filters)[source]

Returns the Authorized Applications for this user

ssh_key_upload(key, label)[source]

Uploads a new SSH Public Key to your profile This key can be used in later Linode deployments.

Parameters:
  • key (str) – 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.
  • label (str) – The name to give this key. This is purely aesthetic.
Returns:

The newly uploaded SSH Key

Return type:

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.

ssh_keys(*filters)[source]

Returns the SSH Public Keys uploaded to your profile

token_create(label=None, expiry=None, scopes=None, **kwargs)[source]

Creates and returns a new Personal Access Token

tokens(*filters)[source]

Returns the Person Access Tokens active for this user

NetworkingGroup

Includes methods for managing your networking systems.

class linode_api4.linode_client.NetworkingGroup(client)[source]
ip_allocate(linode, public=True)[source]

Allocates an IP to a Instance you own. Additional IPs must be requested by opening a support ticket first.

Parameters:
  • linode (Instance or int) – The Instance to allocate the new IP for.
  • public (bool) – If True, allocate a public IP address. Defaults to True.
Returns:

The new IPAddress

Return type:

IPAddress

ips_assign(region, *assignments)[source]

Redistributes IP Addressees within a single region. This function takes a Region and a list of assignments to make, then requests that the assignments take place. If 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()
Parameters:
  • region (str or Region) – The Region in which the assignments should take place. All Instances and IPAddresses involved in the assignment must be within this region.
  • assignments (dct) – Any number of assignments to make. See IPAddress.to for details on how to construct assignments.
shared_ips(linode, *ips)[source]

Shares the given list of IPAddresses with the provided Instance. This will enable the provided Instance to bring up the shared IP Addresses even though it does not own them.

Parameters:
  • linode – The Instance to share the IPAddresses with. This Instance will be able to bring up the given addresses.
  • ips (str or IPAddress) – Any number of IPAddresses to share to the Instance.
Type:

linode: int or Instance

LongviewGroup

Includes methods for interacting with our Longview service.

class linode_api4.linode_client.LongviewGroup(client)[source]
client_create(label=None)[source]

Creates a new LongviewClient, optionally with a given label.

Parameters:

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
  • UnexpectedResponseError – If the returned data from the api does not look as expected.
clients(*filters)[source]

Requests and returns a paginated list of LongviewClients on your account.

subscriptions(*filters)[source]

Requests and returns a paginated list of LongviewSubscriptions available

ObjectStorageGroup

Includes methods for interacting with Linode Objects Storage. For interacting with buckets and objects, use the s3 API directly with a library like boto3.

class linode_api4.linode_client.ObjectStorageGroup(client)[source]

This group encapsulates all endpoints under /object-storage, including viewing available clusters and managing keys.

cancel()[source]

Cancels Object Storage service. This may be a destructive operation. Once cancelled, you will no longer receive the transfer for or be billed for Object Storage, and all keys will be invalidated.

clusters(*filters)[source]

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")
Parameters:filters – Any number of filters to apply to this query.
Returns:A list of Object Storage Clusters that matched the query.
Return type:PaginatedList of ObjectStorageCluster
keys(*filters)[source]

Returns a list of Object Storage Keys active on this account. These keys allow third-party applications to interact directly with Linode Object Storage.

Parameters:filters – Any number of filters to apply to this query.
Returns:A list of Object Storage Keys that matched the query.
Return type:PaginatedList of ObjectStorageKeys
keys_create(label)[source]

Creates a new Object Storage keypair that may be used to interact directly with Linode Object Storage in third-party applications. This response is the only time that “secret_key” will be populated - be sure to capture its value or it will be lost forever.

Parameters:label (str) – The label for this keypair, for identification only.
Returns:The new keypair, with the secret key populated.
Return type:ObjectStorageKeys

SupportGroup

Includes methods for viewing and opening tickets with our support department.

class linode_api4.linode_client.SupportGroup(client)[source]
ticket_open(summary, description, regarding=None)[source]