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
list

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: 2024-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. A public interface's `mac_address` does not change, even if the public interface is deleted and then recreated. (example: 22:00:AB:CD:EF:01, pattern: `[a-zA-Z0-9-]+`)
`public`	`object`	Public interface type.
`updated`	`string (date-time)`	When the interface was last updated. (example: 2024-01-01T00:01:01)
`version`	`integer`	Interface version number that increments when the interface updates.
`vlan`	`string`	The value is `null` if this is not a VLAN interface. (opaque JSON object)
`vpc`	`object`	The value is `null` if this is not a VPC interface.

A list of all the interfaces available for a Linode.

Name	Datatype	Description
`interfaces`	`array`	Any of the following interface types: VPC, public, or VLAN.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Description
`get`	`select`	`linodeId`, `interfaceId`	Beta Returns an interface assigned to a specific Linode. This operation requires the `read_only` grant for the Linode. Learn more... Learn more...
`list`	`select`	`linodeId`	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...
`create`	`insert`	`linodeId`	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...
`update`	`replace`	`linodeId`, `interfaceId`	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`	`delete`	`linodeId`, `interfaceId`	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...
`upgrade`	`exec`	`linodeId`	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
`interfaceId`	`string`	The `id` of the Linode interface.
`linodeId`	`string`	The `id` of the Linode.

`SELECT` examples

get
list

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
WHERE linodeId = '{{ linodeId }}' -- required
AND interfaceId = '{{ interfaceId }}' -- required
;

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
interfaces
FROM linode.linode.interfaces
WHERE linodeId = '{{ linodeId }}' -- required
;

`INSERT` examples

create
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.

 linode-cli linodes interface-add $linodeId \ --firewall_id 123 \ --default_route.ipv4 true \ --default_route.ipv6 true \ --public.ipv4.addresses '[{"address": "192.0.2.141", "primary": true}, {"address": "auto", "primary": false}]' \ --public.ipv6.ranges '[{"range": "2001:0db8::1/64"}, {"range": "/64"}]' 

Learn more...

- CLI: VLAN interface.

 linode-cli linodes interface-add $linodeId \ --vlan.vlan_label my-vlan \ --vlan.ipam_address 192.168.2.2/24 

Learn more...

- CLI: VPC interface.

 linode-cli linodes interface-add $linodeId \ --firewall_id 123 \ --default_route.ipv4 true \ --vpc.subnet_id 321 \ --vpc.ipv4.addresses '[{"address": "10.0.0.1", "primary": true, "nat_1_1_address": "auto"}, {"address": "auto", "primary": false, "nat_1_1_address": null}]' \ --vpc.ipv4.ranges '[{"range": "/28"}, {"range": "10.11.12.0/24"}]' 

Learn more...

Learn more...

INSERT INTO linode.linode.interfaces (
default_route,
firewall_id,
public,
vlan,
vpc,
linodeId
)
SELECT 
'{{ default_route }}',
{{ firewall_id }},
'{{ public }}',
'{{ vlan }}',
'{{ vpc }}',
'{{ linodeId }}'
RETURNING
id,
created,
default_route,
mac_address,
public,
updated,
version,
vlan,
vpc
;

# Description fields are for documentation purposes
- name: interfaces
props:
  - name: linodeId
    value: "{{ linodeId }}"
    description: Required parameter for the interfaces resource.
  - name: default_route
    description: |
      Indicates if the interface serves as the default route when multiple interfaces are eligible for this role. A public interface can have both an IPv4 `default_route` and an IPv6 `default_route`, provided it has at least one IP address of the corresponding type.
    value:
      ipv4: {{ ipv4 }}
      ipv6: {{ ipv6 }}
  - name: firewall_id
    value: {{ firewall_id }}
    description: |
      The enabled firewall to secure a VPC or public interface. Not allowed for VLAN interfaces. If a `firewall_id` is not provided for a VPC or a public interface, then its [default interface firewall](https://techdocs.akamai.com/linode-api/reference/get-linode-interface-firewalls) is used. If a default firewall is not available, and `null` is not specified, the request fails. Setting the `firewall_id` as `null` indicates that no firewall device will be attached to the interface.
  - name: public
    description: |
      Public interface settings. A Linode can have only one public interface. A public interface can have both IPv4 and IPv6 configurations.
    value:
      ipv4:
        addresses:
          - address: "{{ address }}"
            primary: {{ primary }}
      ipv6:
        ranges:
          - range: "{{ range }}"
  - name: vlan
    description: |
      VLAN interface settings. A Linode can have up to three VLAN interfaces, with a unique `vlan_label` for each.
    value:
      ipam_address: "{{ ipam_address }}"
      vlan_label: "{{ vlan_label }}"
  - name: vpc
    description: |
      VPC interface settings. A Linode can have one VPC interface. The maximum number of interfaces allowed on a Linode is three.
    value:
      ipv4:
        addresses:
          - address: "{{ address }}"
            nat_1_1_address: "{{ nat_1_1_address }}"
            primary: {{ primary }}
        ranges:
          - range: "{{ range }}"
      subnet_id: {{ subnet_id }}

`REPLACE` examples

update

Beta Update the configuration of a Linode interface. CLI: Public interface.

 linode-cli linodes interface-update $linodeId $interfaceId \ --default_route.ipv4 true \ --default_route.ipv6 false \ --public.ipv4.addresses '[{"address": "192.0.2.141", "primary": true}, {"address": "auto", "primary": false}]' \ --public.ipv6.ranges '[{"range": "2001:0db8"::1/64"}, {"range": "/64"}]' 

Learn more...

- CLI: VLAN interface.

 linode-cli linodes interface-update $linodeId $interfaceId \ --vlan.vlan_label my-vlan \ --vlan.ipam_address 192.168.2.2/24 

Learn more...

- CLI: VPC interface.

 linode-cli linodes interface-update $linodeId $interfaceId \ --default_route.ipv4 true \ --vpc.subnet_id 321 \ --vpc.ipv4.addresses '[{"address": "10.0.0.1", "primary": true, "nat_1_1_address": "auto"}, {"address": "auto", "primary": false, "nat_1_1_address": null}]' \ --vpc.ipv4.ranges '[{"range": "/28"}, {"range": "10.11.12.0/24"}]' 

Learn more...

Learn more...

REPLACE linode.linode.interfaces
SET 
default_route = '{{ default_route }}',
public = '{{ public }}',
vlan = '{{ vlan }}',
vpc = '{{ vpc }}'
WHERE 
linodeId = '{{ linodeId }}' --required
AND interfaceId = '{{ interfaceId }}' --required
RETURNING
id,
created,
default_route,
mac_address,
public,
updated,
version,
vlan,
vpc;

`DELETE` examples

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...

DELETE FROM linode.linode.interfaces
WHERE linodeId = '{{ linodeId }}' --required
AND interfaceId = '{{ interfaceId }}' --required
;

Lifecycle Methods

upgrade

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.upgrade 
@linodeId='{{ linodeId }}' --required 
@@json=
'{
"config_id": {{ config_id }}, 
"dry_run": {{ dry_run }}
}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

REPLACE examples​

DELETE examples​

Lifecycle Methods​