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 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.get_regions() # /regions

# access a grouped member - note the URL matches the grouping
client.linode.get_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.LinodeClient(token, base_url='https://api.linode.com/v4', user_agent=None)

__init__(token, base_url='https://api.linode.com/v4', user_agent=None)

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

create_domain(domain, master=True, **kwargs)

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

create_image(disk, label=None, description=None)

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

create_nodebalancer(region, **kwargs)

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

create_volume(label, region=None, linode=None, size=20, **kwargs)

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

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 (Linode or int) – The Linode 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

get_account()

Retrieves information about the acting user’s account, such as billing information.

Returns:Returns the acting user’s account information. Return type:Account

get_domains(*filters)

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

get_images(*filters)

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

get_nodebalancers(*filters)

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

get_profile()

Retrieve the acting user’s Profile, containing information about the current user such as their email address, username, and uid.

Returns:The acting user’s profile. Return type:Profile

get_regions(*filters)

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

get_volumes(*filters)

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

linode = None

Access methods related to Linodes - see LinodeGroup for more information

load(target_type, target_id, target_parent_id=None)

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 a Linode object with ID 123, you could do this:

loaded_linode = client.load(Linode, 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 inforamtion

networking = None

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

profile = None

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

support = None

Access methods related to support - see SupportGroup for more information

Groups

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

client.linode.get_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 Linodes, as well as accessing and working with associated features.

class linode.linode_client.LinodeGroup(client)

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)
linodes = client.linode.get_instances() # use the LinodeGroup

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

create_instance(ltype, region, image=None, authorized_keys=None, **kwargs)

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

Create a Linode from an Image

To create a Linode from an Image, call create_instance 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 Linode object. For example:

new_linode, password = client.linode.create_instance(
    "g5-standard-1",
    "us-east",
    image="linode/debian9")

ltype = client.linode.get_types().first()
region = client.get_regions().first()
image = client.get_images().first()

another_linode, password = client.linode.create_instance(
    ltype,
    region,
    image=image)

Create a Linode from StackScript

When creating a Linode 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 Linode with a user created from keys on github:

stackscript = StackScript(client, 10079)

new_linode, password = client.linode.create_instance(
   "g5-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 a Linode from a Backup

To create a new Linode 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 = Linode(client, 123)
snapshot = existing_linode.available_backups.snapshot.current

new_linode = client.linode.create_instance(
    "g5-standard-1",
    "us-east",
    backup=snapshot)

Create an empty Linode

If you want to create an empty Linode that you will configure manually, simply call create_instance with a Type and a Region:

empty_linode = client.linode.create_instance("g5-standard-2", "us-east")

When created this way, the Linode will not be booted and cannot boot successfully until disks and configs are created, or it is otherwise configured.

Parameters:

• ltype (str or LinodeType) – The Linode Type we are creating
• region (str or Region) – The Region in which we are creating the Linode
• image (str or Image) – The Image to deploy to this Linode. If this is provided and no root_pass is given, a password will be generated and returned along with the new Linode.
• stackscript (int or StackScript) – The StackScript to deploy to the new Linode. 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 Linode. 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 Linode
• group (str) – The display group for the new Linode
• booted (bool) – Whether the new Linode should be booted. This will default to True if the Linode is deployed from an Image or Backup.

Returns:

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

Return type:

Linode or tuple(Linode, 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.

create_stackscript(label, script, images, desc=None, public=False, **kwargs)

Creates a new StackScript on your account.

Parameters:

• label (str) – The label for this StackScript.
• script (str) – The script to run when a Linode is deployed with this StackScript. Must begin with a shebang (#!).
• images (list of Image) – A list of Images that this StackScript supports. Linodes 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

get_instances(*filters)

Returns a list of Linodes on your account. You may filter this query to return only Linodes that match specific criteria:

prod_linodes = client.linode.get_instances(Linode.group == "prod")

Parameters:filters – Any number of filters to apply to this query. Returns:A list of Linodes that matched the query. Return type:PaginatedList of Linode

get_kernels(*filters)

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

get_stackscripts(*filters, **kwargs)

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

get_types(*filters)

Returns a list of Linode 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.get_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.linode_client.AccountGroup(client)

create_oauth_client(name, redirect_uri, **kwargs)

Make a new OAuth Client and return it

get_invoices()

Returns Invoices issued to this account

get_oauth_clients(*filters)

Returns the OAuth Clients associated to this account

get_payments()

Returns a list of Payments made to this account

get_settings()

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

get_transfer()

Returns a MappedObject containing the account’s transfer pool data

get_users(*filters)

Returns a list of users on this account

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

ProfileGroup

Includes methods for managing your user.

class linode.linode_client.ProfileGroup(client)

Collections related to your user.

create_personal_access_token(label=None, expiry=None, scopes=None, **kwargs)

Creates and returns a new Personal Access Token

get_apps(*filters)

Returns the Authorized Applications for this user

get_tokens(*filters)

Returns the Person Access Tokens active for this user

NetworkingGroup

Includes methods for managing your networking systems.

class linode.linode_client.NetworkingGroup(client)

allocate_ip(linode)

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

Parameters:linode (Linode or int) – The Linode to allocate the new IP for. Returns:The new IPAddress Return type:IPAddress

assign_ips(region, *assignments)

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 Linode ends up without a public IP, or with more than one private IP, all of the assignments will fail.

Example usage:

linode1 = Linode(client, 123)
linode2 = Linode(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))

Parameters:

• region (str or Region) – The Region in which the assignments should take place. All Linodes 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.

LongviewGroup

Includes methods for interacting with our Longview service.

class linode.linode_client.LongviewGroup(client)

create_client(label=None)

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.

get_clients(*filters)

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

get_subscriptions(*filters)

Requests and returns a paginated list of LongviewSubscriptions available

SupportGroup

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

class linode.linode_client.SupportGroup(client)

open_ticket(summary, description, regarding=None)