Skip to content

Networks API

The NetworksAPI client provides methods for managing Incus networks.

Usage

from incus_sdk import Client

async with Client() as client:
    # List all networks
    networks = await client.networks.list()

    # Get a network by name
    network = await client.networks.get("lxdbr0")

    # Create a new network
    await client.networks.create(
        name="my-network",
        config={
            "ipv4.address": "10.0.0.1/24",
            "ipv4.nat": "true",
            "ipv6.address": "fd42:474b:622d:259d::1/64",
            "ipv6.nat": "true"
        },
        description="My custom network"
    )

    # Update a network
    await client.networks.update(
        name="my-network",
        config={
            "ipv4.dhcp": "true",
            "ipv6.dhcp": "true"
        }
    )

    # Delete a network
    await client.networks.delete("my-network")

Class Documentation

API client for Incus networks.

Source code in incus_sdk/api/networks.py 
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
class NetworksAPI:
    """API client for Incus networks."""

    def __init__(self, client: APIClient):
        """
        Initialize a new NetworksAPI client.

        Args:
            client: The base API client.
        """
        self.client = client

    async def list(self, recursion: int = 1) -> List[Network]:
        """
        List all networks.

        Args:
            recursion: Level of recursion for the response.

        Returns:
            List[Network]: List of networks.
        """
        params = {"recursion": recursion}
        response = await self.client.get("/1.0/networks", params=params)

        networks = []
        for network_data in response.get("metadata", []):
            networks.append(Network(client=self, **network_data))

        return networks

    async def get(self, name: str) -> Network:
        """
        Get a network by name.

        Args:
            name: Name of the network.

        Returns:
            Network: The network.
        """
        response = await self.client.get(f"/1.0/networks/{name}")
        return Network(client=self, **response.get("metadata", {}))

    async def create(
        self,
        name: str,
        config: Dict[str, Any],
        description: str = None,
        type: str = "bridge",
    ) -> Dict[str, Any]:
        """
        Create a new network.

        Args:
            name: Name of the network.
            config: Network configuration.
            description: Description of the network.
            type: Type of network.

        Returns:
            Dict[str, Any]: The operation response.
        """
        data = {"name": name, "type": type, "config": config}

        if description:
            data["description"] = description

        return await self.client.post("/1.0/networks", data=data)

    async def update(self, name: str, config: Dict[str, Any]) -> Dict[str, Any]:
        """
        Update a network.

        Args:
            name: Name of the network.
            config: New configuration.

        Returns:
            Dict[str, Any]: The operation response.
        """
        return await self.client.patch(f"/1.0/networks/{name}", data=config)

    async def replace(self, name: str, config: Dict[str, Any]) -> Dict[str, Any]:
        """
        Replace a network configuration.

        Args:
            name: Name of the network.
            config: New configuration.

        Returns:
            Dict[str, Any]: The operation response.
        """
        return await self.client.put(f"/1.0/networks/{name}", data=config)

    async def delete(self, name: str) -> Dict[str, Any]:
        """
        Delete a network.

        Args:
            name: Name of the network.

        Returns:
            Dict[str, Any]: The operation response.
        """
        return await self.client.delete(f"/1.0/networks/{name}")

    async def rename(self, name: str, new_name: str) -> Dict[str, Any]:
        """
        Rename a network.

        Args:
            name: Current name of the network.
            new_name: New name for the network.

        Returns:
            Dict[str, Any]: The operation response.
        """
        data = {"name": new_name}

        return await self.client.post(f"/1.0/networks/{name}", data=data)

    async def state(self, name: str) -> Dict[str, Any]:
        """
        Get the state of a network.

        Args:
            name: Name of the network.

        Returns:
            Dict[str, Any]: The network state.
        """
        response = await self.client.get(f"/1.0/networks/{name}/state")
        return response.get("metadata", {})

__init__(client)

Initialize a new NetworksAPI client.

Parameters:

Name Type Description Default
client APIClient

The base API client.

 required
Source code in incus_sdk/api/networks.py 
14
15
16
17
18
19
20
21
def __init__(self, client: APIClient):
    """
    Initialize a new NetworksAPI client.

    Args:
        client: The base API client.
    """
    self.client = client

create(name, config, description=None, type='bridge') async

Create a new network.

Parameters:

Name Type Description Default
name str

Name of the network.

 required
config Dict[str, Any]

Network configuration.

 required
description str

Description of the network.

 None
type str

Type of network.

 'bridge'

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation response.
Source code in incus_sdk/api/networks.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
async def create(
    self,
    name: str,
    config: Dict[str, Any],
    description: str = None,
    type: str = "bridge",
) -> Dict[str, Any]:
    """
    Create a new network.

    Args:
        name: Name of the network.
        config: Network configuration.
        description: Description of the network.
        type: Type of network.

    Returns:
        Dict[str, Any]: The operation response.
    """
    data = {"name": name, "type": type, "config": config}

    if description:
        data["description"] = description

    return await self.client.post("/1.0/networks", data=data)

delete(name) async

Delete a network.

Parameters:

Name Type Description Default
name str

Name of the network.

 required

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation response.
Source code in incus_sdk/api/networks.py 
107
108
109
110
111
112
113
114
115
116
117
async def delete(self, name: str) -> Dict[str, Any]:
    """
    Delete a network.

    Args:
        name: Name of the network.

    Returns:
        Dict[str, Any]: The operation response.
    """
    return await self.client.delete(f"/1.0/networks/{name}")

get(name) async

Get a network by name.

Parameters:

Name Type Description Default
name str

Name of the network.

 required

Returns:

Name Type Description
Network Network

The network.
Source code in incus_sdk/api/networks.py 
42
43
44
45
46
47
48
49
50
51
52
53
async def get(self, name: str) -> Network:
    """
    Get a network by name.

    Args:
        name: Name of the network.

    Returns:
        Network: The network.
    """
    response = await self.client.get(f"/1.0/networks/{name}")
    return Network(client=self, **response.get("metadata", {}))

list(recursion=1) async

List all networks.

Parameters:

Name Type Description Default
recursion int

Level of recursion for the response.

 1

Returns:

Type Description
List[Network]

List[Network]: List of networks.
Source code in incus_sdk/api/networks.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
async def list(self, recursion: int = 1) -> List[Network]:
    """
    List all networks.

    Args:
        recursion: Level of recursion for the response.

    Returns:
        List[Network]: List of networks.
    """
    params = {"recursion": recursion}
    response = await self.client.get("/1.0/networks", params=params)

    networks = []
    for network_data in response.get("metadata", []):
        networks.append(Network(client=self, **network_data))

    return networks

rename(name, new_name) async

Rename a network.

Parameters:

Name Type Description Default
name str

Current name of the network.

 required
new_name str

New name for the network.

 required

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation response.
Source code in incus_sdk/api/networks.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
async def rename(self, name: str, new_name: str) -> Dict[str, Any]:
    """
    Rename a network.

    Args:
        name: Current name of the network.
        new_name: New name for the network.

    Returns:
        Dict[str, Any]: The operation response.
    """
    data = {"name": new_name}

    return await self.client.post(f"/1.0/networks/{name}", data=data)

replace(name, config) async

Replace a network configuration.

Parameters:

Name Type Description Default
name str

Name of the network.

 required
config Dict[str, Any]

New configuration.

 required

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation response.
Source code in incus_sdk/api/networks.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
async def replace(self, name: str, config: Dict[str, Any]) -> Dict[str, Any]:
    """
    Replace a network configuration.

    Args:
        name: Name of the network.
        config: New configuration.

    Returns:
        Dict[str, Any]: The operation response.
    """
    return await self.client.put(f"/1.0/networks/{name}", data=config)

state(name) async

Get the state of a network.

Parameters:

Name Type Description Default
name str

Name of the network.

 required

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The network state.
Source code in incus_sdk/api/networks.py 
134
135
136
137
138
139
140
141
142
143
144
145
async def state(self, name: str) -> Dict[str, Any]:
    """
    Get the state of a network.

    Args:
        name: Name of the network.

    Returns:
        Dict[str, Any]: The network state.
    """
    response = await self.client.get(f"/1.0/networks/{name}/state")
    return response.get("metadata", {})

update(name, config) async

Update a network.

Parameters:

Name Type Description Default
name str

Name of the network.

 required
config Dict[str, Any]

New configuration.

 required

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The operation response.
Source code in incus_sdk/api/networks.py 
81
82
83
84
85
86
87
88
89
90
91
92
async def update(self, name: str, config: Dict[str, Any]) -> Dict[str, Any]:
    """
    Update a network.

    Args:
        name: Name of the network.
        config: New configuration.

    Returns:
        Dict[str, Any]: The operation response.
    """
    return await self.client.patch(f"/1.0/networks/{name}", data=config)

Methods

list

async def list(recursion: int = 1) -> List[Network]

List all networks.

Parameters: - recursion: Level of recursion for the response (default: 1).

Returns: - A list of Network objects.

get

async def get(name: str) -> Network

Get a network by name.

Parameters: - name: Name of the network.

Returns: - A Network object.

create

async def create(
    name: str,
    config: Dict[str, Any],
    description: str = None,
    type: str = "bridge",
) -> Dict[str, Any]

Create a new network.

Parameters: - name: Name of the network. - config: Network configuration as a dictionary. - description: Description of the network (optional). - type: Type of network (default: "bridge").

Returns: - The operation response as a dictionary.

Example:

# Create a bridge network
await client.networks.create(
    name="my-network",
    config={
        "ipv4.address": "10.0.0.1/24",
        "ipv4.nat": "true",
        "ipv4.dhcp": "true",
        "ipv6.address": "fd42:474b:622d:259d::1/64",
        "ipv6.nat": "true",
        "ipv6.dhcp": "true"
    },
    description="My custom network",
    type="bridge"
)

update

async def update(
    name: str, 
    config: Dict[str, Any]
) -> Dict[str, Any]

Update a network.

Parameters: - name: Name of the network. - config: New configuration as a dictionary.

Returns: - The operation response as a dictionary.

Note: This method performs a partial update of the network configuration, only modifying the specified fields.

replace

async def replace(
    name: str, 
    config: Dict[str, Any]
) -> Dict[str, Any]

Replace a network configuration.

Parameters: - name: Name of the network. - config: New configuration as a dictionary.

Returns: - The operation response as a dictionary.

Note: This method replaces the entire network configuration with the provided configuration.

delete

async def delete(
    name: str
) -> Dict[str, Any]

Delete a network.

Parameters: - name: Name of the network.

Returns: - The operation response as a dictionary.

rename

async def rename(
    name: str, 
    new_name: str
) -> Dict[str, Any]

Rename a network.

Parameters: - name: Current name of the network. - new_name: New name for the network.

Returns: - The operation response as a dictionary.

state

async def state(
    name: str
) -> Dict[str, Any]

Get the state of a network.

Parameters: - name: Name of the network.

Returns: - The network state as a dictionary.

Example:

# Get the state of a network
state = await client.networks.state("lxdbr0")
print(f"DHCP leases: {state.get('leases')}")