# 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`

  New in version 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`

  New in version 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.