salt/doc/topics/cloud/linode.rst

Getting Started With Linode

Linode is a public cloud host with a focus on Linux instances.

Dependencies

This driver requires the Python requests library to be installed.

Provider Configuration

Configuration Options

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

The version of the Linode API to interact with. Defaults to v3.

poll_interval

The rate of time in milliseconds to poll the Linode API for changes. Defaults to 500.

ratelimit_sleep

The time in seconds to wait before retrying after a ratelimit has been enforced. Defaults to 0.

Example Configuration

Set up the provider cloud configuration file at /etc/salt/cloud.providers or /etc/salt/cloud.providers.d/*.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 Configuration

Configuration 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). See listing images for more 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 (e.g. Newark, NJ, USA). See listing locations for more options.

size

(Required) The size of the VM. This should be a Linode instance type ID (e.g. g6-standard-2). For APIv3, this would be a plan ID (e.g. Linode 2GB). See listing sizes for more options.

password (overrides provider)

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

assign_private_ip

2016.3.0

Whether or not to assign a private key to the VM. Defaults to False.

cloneform

The name of the Linode to clone from.

disk_size

(Deprecated) 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 partition is allocated.

ssh_interface

2016.3.0

The interface with which to connect over SSH. Valid options are private_ips or public_ips. Defaults to public_ips.

If specifying private_ips, the Linodes must be hosted within the same data center and have the Network Helper enabled on your entire account. The instance that is running the Salt-Cloud provisioning command must also have a private IP assigned to it.

Newer accounts created on Linode have the Network Helper setting enabled by default, account-wide. Legacy accounts do not have this setting enabled by default. To enable the Network Helper on your Linode account, please see Linode's Network Helper documentation.

ssh_pubkey

The public key to authorize for SSH with the VM.

swap

The amount of disk space to allocate for the swap partition. Defaults to 256.

Example Configuration

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

my-linode-profile:
    provider: my-linode-provider
    size: g6-standard-1
    image: linode/alpine3.12
    location: us-east

The my-linode-profile can be realized now with a salt command:

salt-cloud -p my-linode-profile my-linode-instance

This will create a salt minion instance named my-linode-instance in Linode. If the command was executed on the salt-master, its Salt key will automatically be signed on the master.

Once the instance has been created with a salt-minion installed, connectivity to it can be verified with Salt:

salt my-linode-instance test.version

A more advanced configuration utlizing all of the configuration options might look like:

my-linode-profile-advanced:
    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

A legacy configuration for use with APIv3 might look like:

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

Migrating to APIv4

Linode APIv3 has been deprecated and will be shutdown in the coming months. You can opt-in to using APIv4 by setting the api_version provider configuration option to v4.

When switching to APIv4, you will also need to generate a new token. See here for more information.

Notable Changes

Move from label references to ID references. The profile configuration parameters location, size, and image have moved from accepting label based references to IDs. See the profile configuration section for more details.

The ``disk_size`` profile configuration parameter has been deprecated. The parameter will not be taken into account when creating new VMs while targeting APIv4. See the disk_size description under the profile configuration section for more details.

The ``boot`` function no longer requires a ``config_id``. A config can be inferred by the API instead when booting.

The ``clone`` function has renamed parameters to match convention. The old version of these parameters will not be supported when targeting APIv4. * datacenter_id has been deprecated in favor of location. * plan_id has been deprecated in favor of size.

The ``get_plan_id`` function has been deprecated and will not be supported by APIv4. IDs are now the only way of referring to a "plan" (or type/size).

Query Utilities

Listing Sizes

Available sizes can be obtained by running one of:

salt-cloud --list-sizes my-linode-provider

salt-cloud -f avail_sizes my-linode-provider

This will list all Linode sizes/types which can be referenced in VM profiles.

my-linode-config:
    g6-standard-1:
        ----------
        class:
            standard
        disk:
            51200
        gpus:
            0
        id:
            g6-standard-1
        label:
            Linode 2GB
        memory:
            2048
        network_out:
            2000
        price:
            ----------
            hourly:
                0.015
            monthly:
                10.0
        successor:
            None
        transfer:
            2000
        vcpus:
            1
        addons:
            ----------
            backups:
                ----------
                price:
                    ----------
                    hourly:
                        0.004
                    monthly:
                        2.5
...SNIP...

Listing Images

Available images can be obtained by running one of:

salt-cloud --list-images my-linode-provider

salt-cloud -f avail_images my-linode-provider

This will list all Linode images which can be referenced in VM profiles. Official images are available under the linode namespace.

my-linode-config:
    ----------
    linode:
        ----------
        linode/alpine3.10:
            ----------
            created:
                2019-06-20T17:17:11
            created_by:
                linode
            deprecated:
                False
            description:
                None
            eol:
                2021-05-01T04:00:00
            expiry:
                None
            id:
                linode/alpine3.10
            is_public:
                True
            label:
                Alpine 3.10
            size:
                300
            type:
                manual
            vendor:
                Alpine
...SNIP...

Listing Locations

Available locations can be obtained by running one of:

salt-cloud --list-locations my-linode-provider

salt-cloud -f avail_locations my-linode-provider

This will list all Linode regions which can be referenced in VM profiles.

my-linode-config:
    ----------
    linode:
        ----------
        us-east:
            ----------
            capabilities:
                - Linodes
                - NodeBalancers
                - Block Storage
                - Object Storage
                - GPU Linodes
                - Kubernetes
            country:
                us
            id:
                us-east
            status:
                ok
...SNIP...

Cloning

To clone a Linode, add a profile with a clonefrom key, and a script_args: -C. clonefrom should be the name of the Linode that is the source for the clone. script_args: -C passes a -C to the salt-bootstrap script, which only configures the minion and doesn't try to install a new copy of salt-minion. This way the minion gets new keys and the keys get pre-seeded on the master, and the /etc/salt/minion file has the right minion 'id:' declaration.

Cloning requires a post 2015-02-01 salt-bootstrap.

It is safest to clone a stopped machine. To stop a machine run

salt-cloud -a stop machine_to_clone

To create a new machine based on another machine, add an entry to your linode cloud profile that looks like this:

li-clone:
  provider: my-linode-config
  clonefrom: machine_to_clone
  script_args: -C -F

Then run salt-cloud as normal, specifying -p li-clone. The profile name can be anything; It doesn't have to be li-clone.

clonefrom: is the name of an existing machine in Linode from which to clone. Script_args: -C -F is necessary to avoid re-deploying Salt via salt-bootstrap. -C will just re-deploy keys so the new minion will not have a duplicate key or minion_id on the Master, and -F will force a rewrite of the Minion config file on the new Minion. If -F isn't provided, the new Minion will have the machine_to_clone's Minion ID, instead of its own Minion ID, which can cause problems.

Note

Pull Request #733 to the salt-bootstrap repo makes the -F argument non-necessary. Once that change is released into a stable version of the Bootstrap Script, the -C argument will be sufficient for the script_args setting.

If the machine_to_clone does not have Salt installed on it, refrain from using the script_args: -C -F altogether, because the new machine will need to have Salt installed.