interfaces
Creates, updates, deletes, gets or lists an interfaces resource.
Overview
| Name | interfaces |
| Type | Resource |
| Id | linode.linode.interfaces |
Fields
The following fields are returned by SELECT queries:
- get_linode_interface
- get_linode_interfaces
Returns a single interface available for a Linode.
| Name | Datatype | Description |
|---|---|---|
id | integer | Read-only The unique ID for this interface. For dry_run upgrades, a unique id is not generated for the interface and its value is set to 0. |
created | string (date-time) | When the interface was created. (example: 2025-01-01T00:01:01) |
default_route | object | Indicates if the interface is used as a default route. |
mac_address | string | A 48-bit MAC address used to identify the Linode's interface. The mac_address of an interface remains constant and does not change. (example: 22:00:AB:CD:EF:01, pattern: [a-zA-Z0-9-]+) |
public | object | Public interface configuration. Null if not a public interface. |
updated | string (date-time) | When the interface was last updated. (example: 2025-01-01T00:01:01) |
version | integer | Interface version number that increments when the interface updates. |
vlan | object | VLAN interface configuration. Null if not a VLAN interface. |
vpc | object | VPC interface configuration. Null if not a VPC interface. |
A list of all the interfaces available for a Linode.
| Name | Datatype | Description |
|---|
Methods
The following methods are available for this resource:
| Name | Accessible by | Required Params | Optional Params | Description |
|---|---|---|---|---|
get_linode_interface | select | Beta Returns an interface assigned to a specific Linode. This operation requires the read_only grant for the Linode.Learn more... Learn more... | ||
get_linode_interfaces | select | Beta This operation returns all interfaces assigned to a specific Linode. They list in the order they were created. On the Linode, interfaces also list in this order, and are typically named eth0, eth1, eth2, and so on. The MAC address is the most reliable method to identify an interface. This operation requires the read_only grant for the Linode. The Linode needs to use interfaces and not configuration profile interfaces. Run Get account settings to see if Linode interfaces are supported.Learn more... Learn more... | ||
post_linode_interface | insert | Beta Creates an interface for the Linode. This interface links to the Linode, rather than to a configuration profile. You can create, delete, or update interfaces when the Linode is either powered off or in the process of being created. Firewalls are applied to the Linode interface, not directly to the Linode itself. You can add, delete, or update these firewalls at any time. This operation requires the read_write grant for the Linode.A successful request triggers an interface_create event.You need to set one interface type: vpc, public, or vlan. Omit the others or set them to null.A Linode can have up to three interfaces: - Only one public interface is allowed on a Linode.- Multiple vlan interfaces are allowed, provided that they belong to distinct VLANs, which have unique vlan_labels.- One vpc interface is allowed.The Linode must be located in a region that supports Linode interfaces. Run Get a region to see if interfaces are supported in that region. CLI: Public interface. <br /> linode-cli linodes interface-add $linodeId \<br /> --firewall_id 123 \<br /> --default_route.ipv4 true \<br /> --default_route.ipv6 true \<br /> --public.ipv4.addresses '[{"address": "192.0.2.141", "primary": true}, {"address": "auto", "primary": false}]' \<br /> --public.ipv6.ranges '[{"range": "2001:0db8::1/64"}, {"range": "/64"}]'<br /> Learn more... - CLI: VLAN interface. <br /> linode-cli linodes interface-add $linodeId \<br /> --vlan.vlan_label my-vlan \<br /> --vlan.ipam_address 192.168.2.2/24<br /> Learn more... - CLI: VPC interface. <br /> linode-cli linodes interface-add $linodeId \<br /> --firewall_id 123 \<br /> --default_route.ipv4 true \<br /> --vpc.subnet_id 321 \<br /> --vpc.ipv4.addresses '[{"address": "10.0.0.1", "primary": true, "nat_1_1_address": "auto"}, {"address": "auto", "primary": false, "nat_1_1_address": null}]' \<br /> --vpc.ipv4.ranges '[{"range": "/28"}, {"range": "10.11.12.0/24"}]'<br /> Learn more... Learn more... | ||
put_linode_interface | replace | Beta Update the configuration of a Linode interface. CLI: Public interface.<br /> linode-cli linodes interface-update $linodeId $interfaceId \<br /> --default_route.ipv4 true \<br /> --default_route.ipv6 false \<br /> --public.ipv4.addresses '[{"address": "192.0.2.141", "primary": true}, {"address": "auto", "primary": false}]' \<br /> --public.ipv6.ranges '[{"range": "2001:0db8"::1/64"}, {"range": "/64"}]'<br /> Learn more... - CLI: VLAN interface. <br /> linode-cli linodes interface-update $linodeId $interfaceId \<br /> --vlan.vlan_label my-vlan \<br /> --vlan.ipam_address 192.168.2.2/24<br /> Learn more... - CLI: VPC interface. <br /> linode-cli linodes interface-update $linodeId $interfaceId \<br /> --default_route.ipv4 true \<br /> --vpc.subnet_id 321 \<br /> --vpc.ipv4.addresses '[{"address": "10.0.0.1", "primary": true, "nat_1_1_address": "auto"}, {"address": "auto", "primary": false, "nat_1_1_address": null}]' \<br /> --vpc.ipv4.ranges '[{"range": "/28"}, {"range": "10.11.12.0/24"}]'<br /> Learn more... Learn more... | ||
delete_linode_interface | delete | Beta Deletes a Linode interface on a specific Linode. To access this operation, you need the read_write grant for the Linode. You can't delete an active interface. First, you need to shut down the associated Linode.Learn more... Learn more... | ||
post_upgrade_linode_interfaces | exec | Beta Automatically upgrades all legacy config interfaces of a single configuration profile to Linode interfaces. A Linode interface is directly associated with the Linode, rather than being tied to a configuration profile. Firewalls are applied to the Linode interface, not directly to the Linode itself. > ❗️ This upgrade is irreversible > > Once you upgrade a Linode to use Linode interfaces, you can't use legacy config interfaces. This means you can no longer use the Linode with any Linode products that require private IPs, such as NodeBalancer. You can use dry_run to preview the upgrade.Before upgrading interfaces, you can check the new Linode interface configuration by performing a dry run, where you set dry_run to true or omit it. A dry_run runs the upgrade logic and returns a JSON representation of what the interface configuration will be after the upgrade without committing any changes.When you run this operation with dry_run set to false, the following occurs:- It creates matching interfaces on the Linode based on the interfaces present on the config_id.- All firewalls are removed from the Linode. Any firewalls that were originally attached to the Linode are now applied to the public and VPC interfaces. If the Linode has no firewalls attached, then default firewalls are not used. - If no legacy config interfaces are defined ( legacy_config) in the config_id, a public interface is created using the public IPv4 assigned to the Linode. The same is the case if the Linode has no config defined.- For public interfaces, the Linode's current MAC address and SLAAC address are conserved. The MAC address won't change. - It deletes all legacy config interfaces from all configs. - It returns the list of interfaces for the Linode. Requirements: - The config_id for the legacy config interfaces can't use a public interface private IPv4 address.- The Linode needs a MAC address in the database if it's IPv6 enabled. If it doesn't, an error message tells you what to do. - The Linode must be in a region that supports Linode interfaces. Run Get a region. - Your account must allow creation of Linodes with Linode interfaces, run Get account settings. - If the Linode has a user with a non-standard username, it can't be upgraded. Learn more... Learn more... |
Parameters
Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.
| Name | Datatype | Description |
|---|
SELECT examples
- get_linode_interface
- get_linode_interfaces
Beta Returns an interface assigned to a specific Linode. This operation requires the read_only grant for the Linode.
Learn more...
Learn more...
SELECT
id,
created,
default_route,
mac_address,
public,
updated,
version,
vlan,
vpc
FROM linode.linode.interfaces;
Beta This operation returns all interfaces assigned to a specific Linode. They list in the order they were created. On the Linode, interfaces also list in this order, and are typically named eth0, eth1, eth2, and so on. The MAC address is the most reliable method to identify an interface. This operation requires the read_only grant for the Linode. The Linode needs to use interfaces and not configuration profile interfaces. Run Get account settings to see if Linode interfaces are supported.
Learn more...
Learn more...
SELECT
*
FROM linode.linode.interfaces;
INSERT examples
- post_linode_interface
- Manifest
Beta Creates an interface for the Linode. This interface links to the Linode, rather than to a configuration profile. You can create, delete, or update interfaces when the Linode is either powered off or in the process of being created.
Firewalls are applied to the Linode interface, not directly to the Linode itself. You can add, delete, or update these firewalls at any time.
This operation requires the read_write grant for the Linode.
A successful request triggers an interface_create event.
You need to set one interface type: vpc, public, or vlan. Omit the others or set them to null.
A Linode can have up to three interfaces:
- Only one public interface is allowed on a Linode.
- Multiple vlan interfaces are allowed, provided that they belong to distinct VLANs, which have unique vlan_labels.
- One vpc interface is allowed.
The Linode must be located in a region that supports Linode interfaces. Run Get a region to see if interfaces are supported in that region. CLI: Public interface.
<br /> linode-cli linodes interface-add $linodeId \<br /> --firewall_id 123 \<br /> --default_route.ipv4 true \<br /> --default_route.ipv6 true \<br /> --public.ipv4.addresses '[{"address": "192.0.2.141", "primary": true}, {"address": "auto", "primary": false}]' \<br /> --public.ipv6.ranges '[{"range": "2001:0db8::1/64"}, {"range": "/64"}]'<br />
Learn more...
- CLI: VLAN interface.
<br /> linode-cli linodes interface-add $linodeId \<br /> --vlan.vlan_label my-vlan \<br /> --vlan.ipam_address 192.168.2.2/24<br />
Learn more...
- CLI: VPC interface.
<br /> linode-cli linodes interface-add $linodeId \<br /> --firewall_id 123 \<br /> --default_route.ipv4 true \<br /> --vpc.subnet_id 321 \<br /> --vpc.ipv4.addresses '[{"address": "10.0.0.1", "primary": true, "nat_1_1_address": "auto"}, {"address": "auto", "primary": false, "nat_1_1_address": null}]' \<br /> --vpc.ipv4.ranges '[{"range": "/28"}, {"range": "10.11.12.0/24"}]'<br />
Learn more...
Learn more...
INSERT INTO linode.linode.interfaces (
)
SELECT
;
# Description fields are for documentation purposes
- name: interfaces
props:
REPLACE examples
- put_linode_interface
Beta Update the configuration of a Linode interface. CLI: Public interface.
<br /> linode-cli linodes interface-update $linodeId $interfaceId \<br /> --default_route.ipv4 true \<br /> --default_route.ipv6 false \<br /> --public.ipv4.addresses '[{"address": "192.0.2.141", "primary": true}, {"address": "auto", "primary": false}]' \<br /> --public.ipv6.ranges '[{"range": "2001:0db8"::1/64"}, {"range": "/64"}]'<br />
Learn more...
- CLI: VLAN interface.
<br /> linode-cli linodes interface-update $linodeId $interfaceId \<br /> --vlan.vlan_label my-vlan \<br /> --vlan.ipam_address 192.168.2.2/24<br />
Learn more...
- CLI: VPC interface.
<br /> linode-cli linodes interface-update $linodeId $interfaceId \<br /> --default_route.ipv4 true \<br /> --vpc.subnet_id 321 \<br /> --vpc.ipv4.addresses '[{"address": "10.0.0.1", "primary": true, "nat_1_1_address": "auto"}, {"address": "auto", "primary": false, "nat_1_1_address": null}]' \<br /> --vpc.ipv4.ranges '[{"range": "/28"}, {"range": "10.11.12.0/24"}]'<br />
Learn more...
Learn more...
REPLACE linode.linode.interfaces
SET
-- No updatable properties
WHERE
;
DELETE examples
- delete_linode_interface
Beta Deletes a Linode interface on a specific Linode. To access this operation, you need the read_write grant for the Linode. You can't delete an active interface. First, you need to shut down the associated Linode.
Learn more...
Learn more...
DELETE FROM linode.linode.interfaces;
Lifecycle Methods
- post_upgrade_linode_interfaces
Beta Automatically upgrades all legacy config interfaces of a single configuration profile to Linode interfaces. A Linode interface is directly associated with the Linode, rather than being tied to a configuration profile.
Firewalls are applied to the Linode interface, not directly to the Linode itself.
> ❗️ This upgrade is irreversible
>
> Once you upgrade a Linode to use Linode interfaces, you can't use legacy config interfaces. This means you can no longer use the Linode with any Linode products that require private IPs, such as NodeBalancer. You can use dry_run to preview the upgrade.
Before upgrading interfaces, you can check the new Linode interface configuration by performing a dry run, where you set dry_run to true or omit it. A dry_run runs the upgrade logic and returns a JSON representation of what the interface configuration will be after the upgrade without committing any changes.
When you run this operation with dry_run set to false, the following occurs:
- It creates matching interfaces on the Linode based on the interfaces present on the config_id.
- All firewalls are removed from the Linode. Any firewalls that were originally attached to the Linode are now applied to the public and VPC interfaces. If the Linode has no firewalls attached, then default firewalls are not used.
- If no legacy config interfaces are defined (legacy_config) in the config_id, a public interface is created using the public IPv4 assigned to the Linode. The same is the case if the Linode has no config defined.
- For public interfaces, the Linode's current MAC address and SLAAC address are conserved. The MAC address won't change.
- It deletes all legacy config interfaces from all configs.
- It returns the list of interfaces for the Linode.
Requirements:
- The config_id for the legacy config interfaces can't use a public interface private IPv4 address.
- The Linode needs a MAC address in the database if it's IPv6 enabled. If it doesn't, an error message tells you what to do.
- The Linode must be in a region that supports Linode interfaces. Run Get a region.
- Your account must allow creation of Linodes with Linode interfaces, run Get account settings.
- If the Linode has a user with a non-standard username, it can't be upgraded.
Learn more...
Learn more...
EXEC linode.linode.interfaces.post_upgrade_linode_interfaces
@@json=
'{
"config_id": {{ config_id }},
"dry_run": {{ dry_run }}
}';