API
  1. Linode instances
  2. Linode instances

Create a Linode

post
https://api.linode.com//linode/instances

Creates a new Linode instance on your account. This incurs a charge on your account.

  • There are several types of Linode you can choose from. Each provides a different size, processing potential, and cost. Run the List Linode types operation for information on each available type.

  • You can create a Linode in any available regions. Run the List regions operation to see what's available.

  • You need to provide at least one authentication mechanism for disk access: a root_pass, authorized_keys, or authorized_users, with the latter two offering SSH protection.

  • To fight spam, Akamai restricts outbound connections on ports 25, 465, and 587 on all Linodes. For more information, see our guide on Running a Mail Server.

  • To add or modify tags on a Linode, your account user needs read-write access for Linode instances and Tags operations. Talk to your local account administrator about access management.

There are several ways to create a Linode, using the objects available in this operation:

Use an Image

This includes using a Linode public image distribution or a private image that you created, based on another Linode.

👍

There are tutorials

We offer example API workflows you can follow for both public image distributions as well as private images.

Use cloud-init

Our cloud-init solution with Metadata automates system configuration and software installation by providing a base-64 encoded cloud-config file.

  • You need a compatible image. To check for compatibility, run the List images operation and check for cloud-init under capabilities.

  • This also requires a compatible region. Run the List regions operation and look for Metadata under capabilities for a specific region.

Use a StackScript

You can use a StackScript to automate deployment of new systems, through a customized script.

👍

There's a tutorial

We offer an example API workflow you can follow to create a new Linode using a StackScript.

Use a Linode backup

You can create a backup of an existing Linode and restore it to a new one.

👍

There's a tutorial

We offer an example API workflow you can follow to create a new Linode using a backup.

Attached to a private VLAN

  • See the interfaces object in the Body Params section for details.

  • For more information, see our guide on Getting Started with VLANs.

Create an empty Linode

📘

You should only use this method for advanced use cases.

Linodes and interfaces

Depending on your account settings, you can choose between legacy configuration interfaces or Linode interfaces when creating a Linode. Only one type of interface is allowed per Linode. The interface_generation field lets you select one interface type for new Linodes when both legacy and Linode interfaces options are available on your account. If a Linode is configured with a Linode interface, legacy configuration interfaces can no longer be used on that Linode.

Permissions and scopes

To call this operation, you need the following:

  • Identity and access permissions. Your user needs a role with these permissions assigned. Learn more.

    • Permissions: create_linode

  • OAuth scopes. Your user needs these scopes assigned. Learn more.

    • Scopes: linodes:read_write

CLI

linode-cli linodes create \
  --label linode123 \
  --root_pass aComplex@Password \
  --booted true \
  --stackscript_id 10079 \
  --stackscript_data '{"gh_username": "linode"}' \
  --region us-east \
  --disk_encryption enabled\
  --placement_group.id 528 \
  --type g6-standard-2 \
  --authorized_keys "ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer" \
  --authorized_users "myUser" \
  --authorized_users "secondaryUser" \
  --metadata.user_data "I2Nsb3VkLWNvbmZpZw==" \
  --firewall_id 9000

Learn more

Path Params
string
enum
required

Enum Call either the v4 URL, or v4beta for operations still in Beta.

Allowed:
Body Params

Common properties for creating and rebuilding Linodes.

authorized_keys
array of strings

Write-only A list of public SSH keys that will be automatically appended to the root user's ~/.ssh/authorized_keys file when deploying from an image.

📘

You need to set at least one form of authentication to access a Linode disk. This can be authorized_keys, authorized_users, or a root_pass. You can optionally combine authorized_keys with a root_pass for added security.

authorized_keys
authorized_users
array of strings

Write-only A list of usernames for authorized users. Before you can add a user, it needs an SSH key assigned to its profile. See Add an SSH key for more information. If the usernames already have associated SSH keys, the keys will be appended to the root users ~/.ssh/authorized_keys file automatically when deploying from an image.

📘

You need to set at least one form of authentication to access a Linode disk. This can be authorized_users, authorized_keys or a root_pass. You can optionally combine authorized_users with a root_pass for added security.

authorized_users
boolean
Defaults to true

Write-only The boot status of the Linode after deployment. This defaults to true if you create the Linode using an image or from a backup. Set this to false to have it remain offline after deployment.

string
enum

Whether disk encryption is applied on this Linode. Local disk encryption ensures that your data is secured. Disk encryption protects against unauthorized data access by keeping the data encrypted if the disk is ever removed from the data center, decommissioned, or disposed of. The platform manages the encryption and decryption for you.

By default, encryption is enabled on all Linodes. If you opted out of encryption or if the Linode was created prior to local disk encryption support, you can encrypt your data using the Rebuild a Linode operation.

Allowed:
string | null

The identifier assigned to the disk image to be deployed to the new Linode. You can run the List images operation with authentication to view all available images, and store the id from the applicable one. Official Linode images start with linode/, while any custom images available on your account start with private/. To create a disk from a private/ image, you need read_only or read_write permissions for it. Run the Update a user's grants operation to adjust permissions for a private/ image, or talk to your local account administrator.

string
enum

Defines the maintenance policy for this Linode. This can be one of two policies:

  • linode/migrate. This migrates the Linode to a new host while it remains fully operational, but with some performance degradation. This focuses on maximizing availability.

  • linode/power_off_on. This powers off the Linode at the start of the maintenance event and reboots it once the maintenance finishes. This focuses on maximizing performance.

Review the maintenance policy documentation for more details.

Allowed:
metadata
object

Write-only An object containing user-defined data relevant to the creation of Linodes.

password
length between 7 and 128

Write-only This sets the root user's password on a newly created Linode disk when deploying from an image. A root_pass needs to meet a password strength score requirement that is calculated internally by the API. If the strength requirement isn't met, you'll receive a Password does not meet strength requirement error.

📘

You need to set at least one form of authentication to access a Linode disk. This can be a root_pass, authorized_keys, or authorized_users. You can optionally combine a root_pass and either authorized_keys or authorized_users for added security.

stackscript_data
object

This field is required only if the StackScript being deployed requires input data from the user for successful completion. See Declare user-defined fields (UDFs) for more details.

  • This field needs to be formatted in valid JSON.

  • The total length can't exceed 65,535 characters.

integer

An identifier for a StackScript that to be run during deployment of this Linode. A compatible image is required to use a StackScript. To get a list of available StackScripts and their permitted images, run the List StackScripts operation. This field can't be used when deploying from a backup or a private image.

integer

A unique identifier for a backup taken for another Linode. You can run the List backups operation to see a Linode's available backups. Consider these points when targeting a backup_id:

  • Your user needs read_write access to that Linode.

  • The backup needs to have a status of successful.

  • The Linode needs to be deployed to the same region as the backup.

  • This field and the image field are mutually exclusive.

boolean

If this field is set to true, the created Linode will automatically be enrolled in the Linode Backup service. Consider these points when applying this service:

  • This incurs an additional charge. The cost for the Linode Backup service depends on the type of Linode deployed.

  • This option is always treated as true if the account-wide backups_enabled setting is true. See Get account settings for more information.

  • Linode Backups pricing is included in the response from the List types operation.

integer

Write-only Specifies the size in MB of the primary boot disk. Consider these points when setting a boot_size:

  • The minimum boot disk size is 8,192 MB.

  • The combined boot_size and swap_size can't exceed the overall size of a disk.

  • Any remaining disk space beyond the boot_size and swap-size partition is left unallocated.

integer | null
≥ -1

The firewall to attach this Linode to upon creation. This firewall_id field is for Linodes using VLAN and legacy configuration profile interfaces only. Setting firewall_id to -1 indicates that no firewall device will be attached. If the firewall_id is not provided or is set to null, the default firewall assigned to this Linode will be used, if available.

string
deprecated

Deprecated, Filterable The group label for this Linode.

string | null
enum

Specifies the interface type for the Linode. The value can be either legacy_config or linode. The default value is determined by the interfaces_for_new_linodes setting in your account settings. If the interface_generation option is set to linode, legacy configuration interfaces can no longer be used on the Linode.

  • If interfaces_for_new_linodes is set to linode_only, set interface_generation to linode or omit it for Linode interfaces.

  • If interfaces_for_new_linodes is set to legacy_config_only, set interface_generation to legacy_config or omit it for legacy configuration interfaces.

  • If interfaces_for_new_linodes is set to linode_default_but_legacy_config_allowed, set interface_generation to linode or omit it for Linode interfaces, and to legacy_config if the Linode uses legacy configuration interfaces.

  • If interfaces_for_new_linodes is set to legacy_config_default_but_linode_allowed, set interface_generation to legacy_config or omit it for legacy configuration interfaces, and to linode if the Linode uses Linode interfaces.

Allowed:
interfaces
array of objects
Defaults to []

Interfaces for the Linode. This can be a Linode interface or legacy configuration interface.

interfaces
string
length between 1 and 100

Write-only The identifier value for a kernel to apply on a new Linode instance. Run the List kernels operation to see a list of supported kernels and store the id for the applicable one.

string
length between 3 and 64

Filterable Provides a name for the Linode. If not provided, the API generates one for it. A Linode label has some constraints:

  • It needs to begin and end with an alphanumeric character.

  • It can only consist of alphanumeric characters, hyphens (-), underscores (_), or periods (.).

  • It can't contain two consecutive hyphens (--), underscores (__) or periods (..).

boolean | null

Enables the Network Helper feature. The default value is determined by the network_helper setting in the account settings. This network_helper field is for Linodes using Linode interfaces only.

placement_group
object

Include this to assign this Linode to an existing placement group. These constraints apply:

  • The target placement group needs to be in the same region set for this Linode.

  • The placement group needs to have capacity. Run the Get a region operation and note either the maximum_linodes_per_pg (strict) or maximum_linodes_per_flexible_pg (flexible), based on your selected placement_group_policy. These represent the Linode limit per placement group, for each placement_group_policy type. You can then run the Get a placement group operation to review the Linodes in that group.

boolean

If true, the created Linode will have private networking enabled and assigned a private IPv4 address.

string
required

The region where the Linode will be located.

integer
Defaults to 512

Sets the swap disk size in MB for a new Linode. A swap disk is a dedicated area used by an operating system as an extension of physical system memory.

tags
array of strings

Filterable Tags to help you organize your content.

tags
string
required

The Linode type of the Linode you're creating.

Responses

Response body
object
alerts
object
integer

The percentage of CPU usage required to trigger an alert. If the average CPU usage over two hours exceeds this value, we'll send you an alert. Your Linode's total CPU capacity is represented as 100%, multiplied by its number of cores. For example, a two-core Linode's CPU capacity is represented as 200%. If you want to be alerted at 90% of a two-core Linode's CPU capacity, set the alert value to 180. The default value is 90% multiplied by the number of cores. If the value is set to 0 (zero), the alert is disabled.

integer

The amount of disk IO operation per second required to trigger an alert. If the average disk IO over two hours exceeds this value, we'll send you an alert. If set to 0 (zero), this alert is disabled.

integer

The amount of incoming traffic, in Mbit/s, required to trigger an alert. If the average incoming traffic over two hours exceeds this value, we'll send you an alert. If this is set to 0 (zero), the alert is disabled.

integer

The amount of outbound traffic, in Mbit/s, required to trigger an alert. If the average outbound traffic over two hours exceeds this value, we'll send you an alert. If this is set to 0 (zero), the alert is disabled.

integer

The percentage of network transfer that may be used before an alert is triggered. When this value is exceeded, we'll alert you. If this is set to 0 (zero), the alert is disabled.

backups
object

Information about this Linode's backups status. For information about available backups, run List backups.

boolean

Read-only Whether backups taken for this Linode are available for restoration. Backups undergoing maintenance are not available for restoration.

boolean

Read-only If this Linode has the Backup service enabled. To enable backups, run Enable backups.

date-time

Read-only The last successful backup time. Displayed as null if there was no previous backup.

schedule
object
capabilities
array of strings

Limited availability, Read-only A list of capabilities this Linode supports.

date-time

Read-only When this Linode was created.

string | null
enum
Defaults to enabled

Read-only Indicates the local disk encryption setting for this Linode. If the Linode is part of an LKE cluster, the value is null.

enabled disabled

string
deprecated

Deprecated, Filterable The group label for this Linode.

boolean

Read-only Whether this Linode was provisioned with user_data provided via the Metadata service. See the Create a Linode description for more information on Metadata.

string

Read-only The Linode's host machine identifier.

string
enum

Read-only The virtualization software powering this Linode.

kvm

integer

Filterable, Read-only This Linode's unique identifier, which you need to provide for all operations impacting this Linode.

string | null

The identifier assigned to the disk image to be deployed to the new Linode. You can run the List images operation with authentication to view all available images, and store the id from the applicable one. Official Linode images start with linode/, while any custom images available on your account start with private/. To create a disk from a private/ image, you need read_only or read_write permissions for it. Run the Update a user's grants operation to adjust permissions for a private/ image, or talk to your local account administrator.

string
enum

Filterable, Read-only Indicates if the Linode is configured to use Linode interfaces (linode) or legacy configuration profile interfaces (legacy_config).

legacy_config linode

ipv4
array of strings

Filterable, Read-only This Linode's IPv4 Addresses. Each Linode is assigned a single public IPv4 address upon creation, and may get a single private IPv4 address if needed. You may need to Open a support ticket to get additional IPv4 addresses. IPv4 addresses may be reassigned between your Linodes, or shared with other Linodes. See the networking operations for details.

string | null

Read-only This Linode's IPv6 SLAAC address. This address is specific to a Linode, and may not be shared. If the Linode has not been assigned an IPv6 address, the return value will be null.

string
length between 3 and 64

Filterable Provides a name for the Linode. If not provided, the API generates one for it. A Linode label has some constraints:

  • It needs to begin and end with an alphanumeric character.

  • It can only consist of alphanumeric characters, hyphens (-), underscores (_), or periods (.).

  • It can't contain two consecutive hyphens (--), underscores (__) or periods (..).

integer | null

Read-only The ID of the Kubernetes cluster if the Linode is part of cluster.

string
enum

The maintenance policy configured by the user for this Linode. Review maintenance policy documentation for more details.

linode/migrate linode/power_off_on

placement_group
object | null

Read-only Details on the placement group that this Linode belongs to. Empty if the Linode isn't in a placement group.

integer

The placement group's ID. You need to provide it for all operations that affect it.

string
length ≥ 1

Filterable The unique name set for the placement group. A label has these constraints:

  • It needs to begin and end with an alphanumeric character.
  • It can only consist of alphanumeric characters, hyphens (-), underscores (_), or periods (.).
string
enum

How requests to add future Linodes to your placement group are handled, and whether it remains compliant:

  • strict. Don't assign a new Linode if it breaks the grouped-together or spread-apart model set by the placement_group_type. Use this to ensure the placement group stays compliant (is_compliant: true).
  • flexible. Assign a new Linode, even if it breaks the grouped-together or spread-apart model set by the placement_group_type. This makes the group non-compliant (is_compliant: false). You need to wait for Akamai to move the offending Linode to make it compliant again, once the necessary capacity is available in the region. Offers flexibility to add future Linodes if compliance isn't an immediate concern.

​​​​​

📘

In rare cases, non-compliance can occur with a strict placement group if Akamai needs to failover or migrate your Linodes for maintenance. Fixing non-compliance for a strict placement group is prioritized over a flexible group.

strict flexible

string
enum

Filterable, Read-only How Linodes are distributed in your placement group. A placement_group_type using anti-affinity (anti_affinity:local) places Linodes in separate hosts, but still in the same region. This best supports the spread-apart model for high availability. A placement_group_type using affinity places Linodes physically close together, possibly on the same host. This supports the grouped-together model for low-latency.

📘

Currently, only anti_affinity:local is available for placement_group_type.

anti_affinity:local

string

Filterable, Read-only The region where you've deployed the Linode. A region can only be changed by migrating to a new data center.

string
enum

Read-only The Linode region's site type. A core region indicates a traditional cloud computing region that offers all compute services. A distributed region indicates sites that are globally dispersed to be closer to end users and workloads. These regions offer limited services.

core distributed

specs
object

Read-only Information about the resources available to this Linode.

integer

Read-only The number of video processing units (VPU) this Linode has access to. This applies to a NETINT Quadra T1U VPU-backed accelerated Linode. Displayed as 0 for all non-accelerated Linodes.

integer

Read-only The amount of storage space, in MB, this Linode has access to. A typical Linode divides this space between a primary disk with an image deployed to it, and a swap disk, usually 512 MB. This is the default configuration created when deploying a Linode with an image through Create a Linode. While this configuration is suitable for most use cases, if you need finer control over your Linode's disks, see the List disks operations.

integer

Read-only The number of graphical processing units (GPU) this Linode has access to. This applies to a GPU Linode. Displayed as 0 for all non-GPU Linodes.

integer

Read-only The amount of RAM, in MB, this Linode has access to. Typically, a Linode boots with all of its available RAM, but this can be configured in a config profile. See the List config profiles operation for more information.

integer

Read-only The amount of network transfer this Linode is allotted each month.

integer

Read-only The number of virtual central processing units (vCPU) this Linode has access to. This applies to a high memory Linode. Displayed as 0 for all non-high memory Linodes.

string
enum

Read-only A brief description of the Linode's current state. This value can change without direct action from you. For example, when a Linode goes into maintenance mode, its status is stopped. Status is generally self-explanatory, based on its name.

  • busy indicates you've assigned the Linode to a placement group, but the Linode is currently booting. Once the boot completes, the API completes the assignment and updates the Linode's status accordingly.

  • provisioning indicates that the API is applying operating system or Marketplace applications on the Linode.

  • billing_suspension indicates that payment is past due on the Linode, so we've suspended its use.

running offline booting busy rebooting shutting_down provisioning deleting migrating rebuilding cloning restoring stopped billing_suspension

tags
array of strings

Filterable Tags to help you organize your content.

string

Read-only The type that this Linode was deployed with. To change a Linode's type, use Resize a Linode.

date-time

Read-only When this Linode was last updated.

boolean

The watchdog, named Lassie, is a Shutdown Watchdog that monitors your Linode and reboots it if it powers off unexpectedly. It works by issuing a boot job when your Linode powers off without a shutdown job being responsible. To prevent a loop, Lassie gives up if there have been more than 5 boot jobs issued within 15 minutes.

Updated 26 days ago

Did this page help you?
Language
Credentials

Updated 26 days ago

Did this page help you?