salt.cloud.clouds.linode

The Linode Cloud Module

The Linode cloud module is used to interact with the Linode Cloud.

Provider

The following provider parameters are supported:

  • apikey: (required) The key to use to authenticate with the Linode API.

  • password: (required) The default password to set on new VMs. Must be 8 characters with at least one lowercase, uppercase, and numeric.

  • poll_interval: (optional) The rate of time in milliseconds to poll the Linode API for changes. Defaults to 500.

  • ratelimit_sleep: (optional) The time in seconds to wait before retrying after a ratelimit has been enforced. Defaults to 0.

Note

APIv3 usage has been removed in favor of APIv4. To move to APIv4 now, See the full migration guide here https://docs.saltproject.io/en/latest/topics/cloud/linode.html#migrating-to-apiv4.

Set up the provider configuration at /etc/salt/cloud.providers or /etc/salt/cloud.providers.d/linode.conf:

my-linode-provider:
    driver: linode
    apikey: f4ZsmwtB1c7f85Jdu43RgXVDFlNjuJaeIYV8QMftTqKScEB2vSosFSr...
    password: F00barbazverylongp@ssword

Profile

The following profile parameters are supported:

  • size: (required) The size of the VM. This should be a Linode instance type ID (i.e. g6-standard-2). Run salt-cloud -f avail_sizes my-linode-provider for options.

  • location: (required) The location of the VM. This should be a Linode region (e.g. us-east). Run salt-cloud -f avail_locations my-linode-provider for options.

  • image: (required) The image to deploy the boot disk from. This should be an image ID (e.g. linode/ubuntu22.04); official images start with linode/. Run salt-cloud -f avail_images my-linode-provider for more options.

  • password: (*required) The default password for the VM. Must be provided at the profile or provider level.

  • assign_private_ip: (optional) Whether or not to assign a private IP to the VM. Defaults to False.

  • backups_enabled: (optional) Whether or not to enable the backup for this VM. Backup can be configured in your Linode account Defaults to False.

  • ssh_interface: (optional) The interface with which to connect over SSH. Valid options are private_ips or public_ips. Defaults to public_ips.

  • ssh_pubkey: (optional) The public key to authorize for SSH with the VM.

  • swap: (optional) The amount of disk space to allocate for the swap partition. Defaults to 256.

  • clonefrom: (optional) The name of the Linode to clone from.

Set up a profile configuration in /etc/salt/cloud.profiles.d/:

my-linode-profile:
    # a minimal configuration
    provider: my-linode-provider
    size: g6-standard-1
    image: linode/ubuntu22.04
    location: us-east

my-linode-profile-advanced:
    # an advanced configuration
    provider: my-linode-provider
    size: g6-standard-3
    image: linode/ubuntu22.04
    location: eu-west
    password: bogus123X
    assign_private_ip: true
    ssh_interface: private_ips
    ssh_pubkey: ssh-rsa AAAAB3NzaC1yc2EAAAADAQAB...
    swap_size: 512

Migrating to APIv4

You will need to generate a new token for your account. See https://www.linode.com/docs/products/tools/api/get-started/#create-an-api-token

There are a few changes to note: - There has been a general move from label references to ID references. The profile configuration parameters location, size, and image have moved from being label based references to IDs. See the profile section for more information. In addition to these inputs being changed, avail_sizes, avail_locations, and avail_images now output options sorted by ID instead of label. - The disk_size profile configuration parameter has been deprecated and will not be taken into account when creating new VMs while targeting APIv4.

maintainer:

Linode Developer Tools and Experience Team <dev-dx@linode.com>

depends:

requests

class salt.cloud.clouds.linode.LinodeAPI
abstract avail_images()

avail_images implementation

abstract avail_locations()

avail_locations implementation

abstract avail_sizes()

avail_sizes implementation

abstract boot(name=None, kwargs=None)

boot implementation

abstract clone(kwargs=None)

clone implementation

abstract create(vm_)

create implementation

abstract create_config(kwargs=None)

create_config implementation

abstract destroy(name)

destroy implementation

abstract get_config_id(kwargs=None)

get_config_id implementation

get_linode(kwargs=None)
abstract list_nodes()

list_nodes implementation

abstract list_nodes_full()

list_nodes_full implementation

abstract list_nodes_min()

list_nodes_min implementation

list_nodes_select(call)
abstract reboot(name)

reboot implementation

abstract show_instance(name)

show_instance implementation

abstract show_pricing(kwargs=None)

show_pricing implementation

abstract start(name)

start implementation

abstract stop(name)

stop implementation

class salt.cloud.clouds.linode.LinodeAPIv4
avail_images()

avail_images implementation

avail_locations()

avail_locations implementation

avail_sizes()

avail_sizes implementation

boot(name=None, kwargs=None)

boot implementation

clone(kwargs=None)

clone implementation

create(vm_)

create implementation

create_config(kwargs=None)

create_config implementation

destroy(name)

destroy implementation

classmethod get_api_instance()
get_config_id(kwargs=None)

get_config_id implementation

list_nodes()

list_nodes implementation

list_nodes_full()

list_nodes_full implementation

list_nodes_min()

list_nodes_min implementation

reboot(name)

reboot implementation

set_backup_schedule(label, linode_id, day, window, auto_enable=False)
show_instance(name)

show_instance implementation

show_pricing(kwargs=None)

show_pricing implementation

start(name)

start implementation

stop(name)

stop implementation

salt.cloud.clouds.linode.avail_images(call=None)

Return available Linode images.

CLI Example:

salt-cloud --list-images my-linode-config
salt-cloud -f avail_images my-linode-config
salt.cloud.clouds.linode.avail_locations(call=None)

Return available Linode datacenter locations.

CLI Example:

salt-cloud --list-locations my-linode-config
salt-cloud -f avail_locations my-linode-config
salt.cloud.clouds.linode.avail_sizes(call=None)

Return available Linode sizes.

CLI Example:

salt-cloud --list-sizes my-linode-config
salt-cloud -f avail_sizes my-linode-config
salt.cloud.clouds.linode.boot(name=None, kwargs=None, call=None)

Boot a Linode.

name

The name of the Linode to boot. Can be used instead of linode_id.

linode_id

The ID of the Linode to boot. If provided, will be used as an alternative to name and reduces the number of API calls to Linode by one. Will be preferred over name.

config_id

The ID of the Config to boot. Required.

check_running

Defaults to True. If set to False, overrides the call to check if the VM is running before calling the linode.boot API call. Change check_running to True is useful during the boot call in the create function, since the new VM will not be running yet.

Can be called as an action (which requires a name):

salt-cloud -a boot my-instance config_id=10

...or as a function (which requires either a name or linode_id):

salt-cloud -f boot my-linode-config name=my-instance config_id=10
salt-cloud -f boot my-linode-config linode_id=1225876 config_id=10
salt.cloud.clouds.linode.clone(kwargs=None, call=None)

Clone a Linode.

linode_id

The ID of the Linode to clone. Required.

location

The location of the new Linode. Required.

size

The size of the new Linode (must be greater than or equal to the clone source). Required.

CLI Example:

salt-cloud -f clone my-linode-config linode_id=1234567 location=us-central size=g6-standard-1
salt.cloud.clouds.linode.create(vm_)

Create a single Linode VM.

salt.cloud.clouds.linode.create_config(kwargs=None, call=None)

Creates a Linode Configuration Profile.

name

The name of the VM to create the config for.

linode_id

The ID of the Linode to create the configuration for.

root_disk_id

The Root Disk ID to be used for this config.

swap_disk_id

The Swap Disk ID to be used for this config.

data_disk_id

The Data Disk ID to be used for this config.

New in version 2016.3.0.

kernel_id

The ID of the kernel to use for this configuration profile.

salt.cloud.clouds.linode.destroy(name, call=None)

Destroys a Linode by name.

name

The name of VM to be be destroyed.

CLI Example:

salt-cloud -d vm_name
salt.cloud.clouds.linode.get_config_id(kwargs=None, call=None)

Returns a config_id for a given linode.

New in version 2015.8.0.

name

The name of the Linode for which to get the config_id. Can be used instead of linode_id.

linode_id

The ID of the Linode for which to get the config_id. Can be used instead of name.

CLI Example:

salt-cloud -f get_config_id my-linode-config name=my-linode
salt-cloud -f get_config_id my-linode-config linode_id=1234567
salt.cloud.clouds.linode.get_configured_provider()

Return the first configured instance.

salt.cloud.clouds.linode.get_linode(kwargs=None, call=None)

Returns data for a single named Linode.

name

The name of the Linode for which to get data. Can be used instead linode_id. Note this will induce an additional API call compared to using linode_id.

linode_id

The ID of the Linode for which to get data. Can be used instead of name.

CLI Example:

salt-cloud -f get_linode my-linode-config name=my-instance
salt-cloud -f get_linode my-linode-config linode_id=1234567
salt.cloud.clouds.linode.list_nodes(call=None)

Returns a list of linodes, keeping only a brief listing.

CLI Example:

salt-cloud -Q
salt-cloud --query
salt-cloud -f list_nodes my-linode-config

Note

The image label only displays information about the VM's distribution vendor, such as "Debian" or "RHEL" and does not display the actual image name. This is due to a limitation of the Linode API.

salt.cloud.clouds.linode.list_nodes_full(call=None)

List linodes, with all available information.

CLI Example:

salt-cloud -F
salt-cloud --full-query
salt-cloud -f list_nodes_full my-linode-config

Note

The image label only displays information about the VM's distribution vendor, such as "Debian" or "RHEL" and does not display the actual image name. This is due to a limitation of the Linode API.

salt.cloud.clouds.linode.list_nodes_min(call=None)

Return a list of the VMs that are on the provider. Only a list of VM names and their state is returned. This is the minimum amount of information needed to check for existing VMs.

New in version 2015.8.0.

CLI Example:

salt-cloud -f list_nodes_min my-linode-config
salt-cloud --function list_nodes_min my-linode-config
salt.cloud.clouds.linode.list_nodes_select(call=None)

Return a list of the VMs that are on the provider, with select fields.

salt.cloud.clouds.linode.reboot(name, call=None)

Reboot a linode.

New in version 2015.8.0.

name

The name of the VM to reboot.

CLI Example:

salt-cloud -a reboot vm_name
salt.cloud.clouds.linode.set_backup_schedule(name=None, kwargs=None, call=None)

Set the backup schedule for a Linode.

name

The name (label) of the Linode. Can be used instead of linode_id.

linode_id

The ID of the Linode instance to set the backup schedule for. If provided, will be used as an alternative to name and reduces the number of API calls to Linode by one. Will be preferred over name.

auto_enable

If True, automatically enable the backup feature for the Linode if it wasn't already enabled. Optional parameter, default to False.

day

Possible values: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday

The day of the week that your Linode's weekly Backup is taken. If not set manually, a day will be chosen for you. Backups are taken every day, but backups taken on this day are preferred when selecting backups to retain for a longer period.

If not set manually, then when backups are initially enabled, this may come back as Scheduling until the day is automatically selected.

window

Possible values: W0, W2, W4, W6, W8, W10, W12, W14, W16, W18, W20, W22

The window in which your backups will be taken, in UTC. A backups window is a two-hour span of time in which the backup may occur.

For example, W10 indicates that your backups should be taken between 10:00 and 12:00. If you do not choose a backup window, one will be selected for you automatically.

If not set manually, when backups are initially enabled this may come back as Scheduling until the window is automatically selected.

Can be called as an action (which requires a name):

salt-cloud -a set_backup_schedule my-linode-instance day=Monday window=W20 auto_enable=True

...or as a function (which requires either a name or linode_id):

salt-cloud -f set_backup_schedule my-linode-provider name=my-linode-instance day=Monday window=W20 auto_enable=True
salt-cloud -f set_backup_schedule my-linode-provider linode_id=1225876 day=Monday window=W20 auto_enable=True
salt.cloud.clouds.linode.show_instance(name, call=None)

Displays details about a particular Linode VM. Either a name or a linode_id must be provided.

New in version 2015.8.0.

name

The name of the VM for which to display details.

CLI Example:

salt-cloud -a show_instance vm_name

Note

The image label only displays information about the VM's distribution vendor, such as "Debian" or "RHEL" and does not display the actual image name. This is due to a limitation of the Linode API.

salt.cloud.clouds.linode.show_pricing(kwargs=None, call=None)

Show pricing for a particular profile. This is only an estimate, based on unofficial pricing sources.

New in version 2015.8.0.

CLI Example:

salt-cloud -f show_pricing my-linode-config profile=my-linode-profile
salt.cloud.clouds.linode.start(name, call=None)

Start a VM in Linode.

name

The name of the VM to start.

CLI Example:

salt-cloud -a stop vm_name
salt.cloud.clouds.linode.stop(name, call=None)

Stop a VM in Linode.

name

The name of the VM to stop.

CLI Example:

salt-cloud -a stop vm_name