# 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