> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/dsx-air/llms.txt.

# air_sdk.endpoints.interfaces

Stub file for interfaces endpoint type hints.

## Classes

| Name                                                                      | Description                                       |
| ------------------------------------------------------------------------- | ------------------------------------------------- |
| [`InterfaceLabels`](#air_sdkendpointsinterfacesinterfacelabels)           | None                                              |
| [`Interface`](#air_sdkendpointsinterfacesinterface)                       | Interface model representing a network interface. |
| [`InterfaceEndpointAPI`](#air_sdkendpointsinterfacesinterfaceendpointapi) | API client for interface endpoints.               |

## Module Contents

```python
class air_sdk.endpoints.interfaces.InterfaceLabels
```

```python
interface_role: str | None
```

```python
scalable_unit: int | None
```

```python
class air_sdk.endpoints.interfaces.Interface
```

**Bases**: `air_sdk.air_model.AirModel`

Interface model representing a network interface.

```python
id: str
```

Unique identifier for the interface

```python
name: str
```

Human-readable name of the interface

```python
created: datetime.datetime
```

Timestamp when the interface was created

```python
modified: datetime.datetime
```

Timestamp when the interface was last modified

```python
node: Node
```

Node that the interface is related to

```python
interface_type: str
```

Type of the interface

```python
mac_address: str
```

MAC address of the interface

```python
connection: Interface | None
```

Interface that the interface is connected to

```python
outbound: bool
```

Whether the interface is outbound

```python
labels: InterfaceLabels | None
```

Labels of the interface

```python
interface_role: str | None
```

The role of the interface

```python
scalable_unit: int | None
```

The scalable unit number of the interface

```python
split: str | None
```

The breakout (split) factor of the interface

```python
get_model_api() -> type[InterfaceEndpointAPI]
```

```python
model_api: InterfaceEndpointAPI
```

```python
update(
    *,
    name: str | dataclasses._MISSING_TYPE = ...,
    interface_type: Literal[DATA_PLANE_INTF, PCIE_INTF, OOB_INTF] | dataclasses._MISSING_TYPE = ...,
    outbound: bool | dataclasses._MISSING_TYPE = ...,
    labels: InterfaceLabels | None | dataclasses._MISSING_TYPE = ...,
    interface_role: str | None | dataclasses._MISSING_TYPE = ...,
    scalable_unit: int | None | dataclasses._MISSING_TYPE = ...
) -> None
```

Update the interface's properties.

**Parameters:**

* `name` – New name for the interface
* `interface_type` – New type for the interface
* `outbound` – New outbound status for the interface
* `labels` – New labels for the interface
* `interface_role` – New role for the interface
* `scalable_unit` – New scalable unit for the interface

**Example:**

```python
>>> interface.update(name='New Name')
```

```python
delete() -> None
```

Delete the interface.

**Example:**

```python
>>> interface.delete()
```

```python
links: LinkEndpointAPI
```

Access the links endpoint for this interface.

**Returns:**

LinkEndpointAPI instance filtered for this interface's links

**Example:**

```python
>>> for link in interface.links.list():
...     print(link.id)
```

```python
breakout(
    *,
    split_count: int
) -> List[Interface]
```

Break out this interface into multiple sub-interfaces.

**Parameters:**

* `split_count` – Number of interfaces to create from the breakout. Must be supported by the node's split_options.

**Returns:**

List of created breakout interfaces

**Example:**

```python
>>> interface = api.interfaces.get('interface-id')
>>> breakout_interfaces = interface.breakout(split_count=4)
>>> # Creates swp1s0, swp1s1, swp1s2, swp1s3
```

> **Note**
>
> * Not available for nodes managed by a platform; use
>   `node.bulk_breakout()` instead

```python
revert_breakout() -> Interface
```

Revert this breakout interface back to a single interface.

Can be called on any of the breakout interfaces - they will all be
reverted and deleted except the first one (s0), which will be renamed
back to the original name.

**Returns:**

The reverted interface

**Example:**

```python
>>> interface = api.interfaces.get('interface-id')  # e.g., swp1s0
>>> reverted = interface.revert_breakout()  # Reverts back to swp1
```

> **Note**
>
> * All breakout interfaces will be deleted except the first one (s0)
> * The s0 interface will be renamed back to the original name
> * Any existing connections on the breakout interfaces are
>   automatically removed
> * Cannot revert if any breakout interface has services attached
> * Not available for nodes managed by a platform; use
>   `node.bulk_breakout()` instead

```python
services: ServiceEndpointAPI
```

Query for the related services of the interface.

**Returns:**

ServiceEndpointAPI instance filtered for this interface's services

**Example:**

```python
>>> for service in interface.services.list():
...     print(f'{service.name}: {service.worker_fqdn}:{service.worker_port}')
>>>
>>> # Create service on this interface
>>> service = interface.services.create(
...     name='SSH', node_port=22, service_type='ssh'
... )
```

```python
class air_sdk.endpoints.interfaces.InterfaceEndpointAPI
```

**Bases**: `air_sdk.air_model.BaseEndpointAPI[air_sdk.endpoints.interfaces.Interface]`

API client for interface endpoints.

```python
API_PATH: str
```

```python
model: type[Interface]
```

```python
create(
    *,
    name: str,
    node: Node | PrimaryKey,
    interface_type: Literal[DATA_PLANE_INTF, PCIE_INTF, OOB_INTF] | dataclasses._MISSING_TYPE = ...,
    mac_address: str | dataclasses._MISSING_TYPE = ...,
    outbound: bool | dataclasses._MISSING_TYPE = ...,
    labels: InterfaceLabels | None | dataclasses._MISSING_TYPE = ...,
    interface_role: str | None | dataclasses._MISSING_TYPE = ...,
    scalable_unit: int | None | dataclasses._MISSING_TYPE = ...,
    split: str | None | dataclasses._MISSING_TYPE = ...
) -> Interface
```

Create a new interface.

**Parameters:**

* `name` – Name of the interface
* `node` – Node to create the interface on
* `interface_type` – Type of the interface
* `mac_address` – MAC address of the interface
* `outbound` – Outbound status of the interface
* `labels` – Labels for the interface
* `interface_role` – Role of the interface
* `scalable_unit` – Scalable unit of the interface
* `split` – Breakout factor of the physical port this interface belongs to ('1x' = un-split, e.g. '2x', '4x'). Only meaningful for nodes managed by a platform where the `name`/`split` pair must match the platforms specifications; when unset, the interface is created at the platform's default split.

**Returns:**

The created Interface instance

**Example:**

```python
>>> interface = api.interfaces.create(name='eth0', node=node)
>>> interface = node.interfaces.create(name='eth0', node=node.id)
>>>
>>> # On a platform-managed node, name/split must match the platforms
>>> # specifications.
>>> interface = api.interfaces.create(name='swp1s1', node=node, split='2x')
```

```python
list(
    *,
    interface_type: Literal[DATA_PLANE_INTF, PCIE_INTF, OOB_INTF] | dataclasses._MISSING_TYPE = ...,
    mac_address: str | dataclasses._MISSING_TYPE = ...,
    name: str | dataclasses._MISSING_TYPE = ...,
    node: Node | PrimaryKey | dataclasses._MISSING_TYPE = ...,
    outbound: bool | dataclasses._MISSING_TYPE = ...,
    simulation: str | dataclasses._MISSING_TYPE = ...,
    limit: int | dataclasses._MISSING_TYPE = ...,
    offset: int | dataclasses._MISSING_TYPE = ...,
    search: str | dataclasses._MISSING_TYPE = ...,
    ordering: str | dataclasses._MISSING_TYPE = ...
) -> Iterator[Interface]
```

List all interfaces with optional filtering.

**Parameters:**

* `interface_type` – Filter by interface type
* `mac_address` – Filter by MAC address
* `name` – Filter by name
* `node` – Filter by node
* `outbound` – Filter by outbound status
* `simulation` – Filter by simulation
* `limit` – Number of results to return per page
* `offset` – The initial index from which to return the results
* `search` – Search by name
* `ordering` – Order by field

**Returns:**

Iterator of Interface instances

**Example:**

```python
>>> # List all interfaces
>>> for interface in api.interfaces.list():
...     print(interface.name)

>>> # Filter by interface type
>>> for interface in api.interfaces.list(interface_type='DATA_PLANE_INTF'):
...     print(interface.name)

>>> # Search by name
>>> for interface in api.interfaces.list(search='eth0'):
...     print(interface.name)

>>> # Order by name descending
>>> for interface in api.interfaces.list(ordering='-name'):
...     print(interface.name)
```

```python
get(pk: PrimaryKey) -> Interface
```

Get a specific interface by ID.

**Parameters:**

* `pk` – The interface ID (string or UUID)

**Returns:**

The Interface instance

**Example:**

```python
>>> interface = api.interfaces.get('interface-id')
```

```python
delete(pk: PrimaryKey) -> None
```

Delete a specific interface by ID.

**Parameters:**

* `pk` – The interface ID (string or UUID)

**Example:**

```python
>>> api.interfaces.delete('interface-id')
```

```python
breakout(
    *,
    interface: Interface | PrimaryKey,
    split_count: int
) -> List[Interface]
```

Break out an interface into multiple sub-interfaces.

Breaks out a data plane interface into multiple sub-interfaces.
For example, breaking out "swp1" with a 4-way split creates
"swp1s0", "swp1s1", "swp1s2", "swp1s3".

**Parameters:**

* `interface` – The interface to break out
* `split_count` – Number of interfaces to create from the breakout. Must be supported by the node's split_options (typically 2, 4, or 8).

**Returns:**

List of all created breakout interfaces

**Example:**

```python
>>> interface = api.interfaces.get('interface-id')
>>> breakout_interfaces = api.interfaces.breakout(  # fmt: skip
...     interface=interface, split_count=4
... )
>>> print([i.name for i in breakout_interfaces])
['swp1s0', 'swp1s1', 'swp1s2', 'swp1s3']
```

> **Note**
>
> * Only data plane interfaces can be broken out
> * Any existing connection on the interface will be automatically removed
> * The original interface is renamed to \<name>s0 and keeps its MAC address
> * New interfaces are created with allocated MAC addresses
> * Not available for nodes managed by a platform; use
>   `bulk_breakout()` instead

```python
revert_breakout(
    *,
    interface: Interface | PrimaryKey
) -> Interface
```

Revert a broken out interface back to a single interface.

Reverts broken out interfaces back to a single interface.
For example, reverting "swp1s0" (along with "swp1s1", "swp1s2", "swp1s3")
back to "swp1". This can be called on any of the breakout interfaces.

**Parameters:**

* `interface` – One of the breakout interfaces (e.g., swp1s0, swp1s1, etc.)

**Returns:**

The reverted interface with its original name

**Example:**

```python
>>> interface = api.interfaces.get('interface-id')  # e.g., swp1s2
>>> reverted = api.interfaces.revert_breakout(interface=interface)
>>> print(reverted.name)
'swp1'
```

> **Note**
>
> * All breakout interfaces will be deleted except the first one (s0)
> * The s0 interface will be renamed back to the original name
> * Any existing connections on the breakout interfaces are
>   automatically removed
> * Cannot revert if any breakout interface has services attached
> * Not available for nodes managed by a platform; use
>   `bulk_breakout()` instead

```python
bulk_breakout(
    *,
    node: Node | PrimaryKey,
    interfaces: List[InterfaceBreakoutEntry]
) -> List[Interface]
```

Re-split several physical ports of a platform-managed node at once.

Each entry names a port by any interface it currently carries and the
split factor to move it to. The whole port is re-laid out from the
platform's specification: every interface it carries is deleted and the
interfaces the platform defines at the target split are created in
their place. Sending the un-split factor (e.g. '1x') reverts a port.

Read each port's current split, supported splits and interface IDs
with `node.breakout_options()`.

**Parameters:**

* `node` – The node the interfaces are stored on.
* `interfaces` – The ports to re-split, as `\{'id': ..., 'split': ...\}` entries. `id` may be an Interface or an interface ID.

**Returns:**

Every interface the request created, in name order

**Example:**

```python
>>> options = node.breakout_options()
>>> swp1 = options['swp1']['interfaces'][0]['id']
>>> created = api.interfaces.bulk_breakout(  # fmt: skip
...     node=node, interfaces=[{'id': swp1, 'split': '4x'}]
... )
>>> print([i.name for i in created])
['swp1s0', 'swp1s1', 'swp1s2', 'swp1s3']
```

> **Note**
>
> * The request is applied in full or not at all
> * Each port that changes split has all of its interfaces replaced:
>   the interfaces it carried, including the one passed in, no longer
>   exist, so use the returned interfaces instead
> * A port already at the requested split is left as it is: its
>   interfaces keep their IDs and are not returned
> * Links on affected interfaces are removed, along with any
>   services on them