salt.cloud.clouds.linode

The Linode Cloud Module

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

You can target a specific version of the Linode API with the api_version parameter. The default is v3.

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.

  • api_version: (optional) The version of the Linode API to interact with. Defaults to v3.

  • 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 is deprecated and will be removed in a future release in favor of APIv4. To move to APIv4 now, set the api_version parameter in your provider configuration to v4. 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
    api_version: v4
    apikey: f4ZsmwtB1c7f85Jdu43RgXVDFlNjuJaeIYV8QMftTqKScEB2vSosFSr...
    password: F00barbaz

For use with APIv3 (deprecated):

my-linode-provider-v3:
    driver: linode
    apikey: f4ZsmwtB1c7f85Jdu43RgXVDFlNjuJaeIYV8QMftTqKScEB2vSosFSr...
    password: F00barbaz

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). For APIv3, this would be a plan ID (i.e. Linode 2GB). 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). For APIv3, this would be a datacenter location (i.e. Newark, NJ, USA). 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/ubuntu16.04); official images start with linode/. For APIv3, this would be an image label (i.e. Ubuntu 16.04). 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 key to the VM. 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.

  • disk_size: (deprecated, optional) The amount of disk space to allocate for the OS disk. This has no effect with APIv4; the size of the boot disk will be the remainder of disk space after the swap parition is allocated.

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/alpine3.12
    location: us-east

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

my-linode-profile-v3:
    # a legacy configuration
    provider: my-linode-provider-v3
    size: Nanode 1GB
    image: Alpine 3.12
    location: Fremont, CA, USA

Migrating to APIv4

In order to target APIv4, ensure your provider configuration has api_version set to v4.

You will also need to generate a new token for your account. See https://www.linode.com/docs/platform/api/getting-started-with-the-linode-api/#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

Charles Kenney <ckenney@linode.com>

maintainer

Phillip Campbell <pcampbell@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)
get_plan_id(kwargs=None)

get_plan_id implementation

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

get_config_id(kwargs=None)

get_config_id implementation

get_plan_id(kwargs=None)

get_plan_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

show_instance(name)

show_instance implementation

show_pricing(kwargs=None)

show_pricing implementation

start(name)

start implementation

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

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

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.

datacenter_id

The ID of the Datacenter where the Linode will be placed. Required for APIv3 usage. Deprecated. Use location instead.

plan_id

The ID of the plan (size) of the Linode. Required. Required for APIv3 usage. Deprecated. Use size instead.

CLI Example:

salt-cloud -f clone my-linode-config linode_id=1234567 datacenter_id=2 plan_id=5
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.get_plan_id(kwargs=None, call=None)

Returns the Linode Plan ID.

label

The label, or name, of the plan to get the ID from.

CLI Example:

salt-cloud -f get_plan_id linode label="Nanode 1GB"
salt-cloud -f get_plan_id linode label="Linode 2GB"
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.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