"""Tenant Layer 2 network resource manager."""
from __future__ import annotations
import builtins
import logging
from typing import TYPE_CHECKING, Any
from pyvergeos.filters import combine_filters, quote_value
from pyvergeos.resources.base import Projected, ResourceManager, ResourceObject
if TYPE_CHECKING:
from pyvergeos.client import VergeClient
from pyvergeos.resources.tenant_manager import Tenant
logger = logging.getLogger(__name__)
# Plain own-columns. The computed entries live on the model below and are
# appended when the full projection is assembled, so an accessor and the
# field list feeding it cannot drift apart (issue #125).
_TENANT_LAYER2_COLUMNS = [
"$key",
"tenant",
"vnet",
"enabled",
]
[docs]
class TenantLayer2Network(ResourceObject):
"""Tenant Layer 2 Network resource object.
Represents a Layer 2 network assignment that provides bridged connectivity
between a parent network and a tenant. Layer 2 networks allow tenants
direct access to parent network segments.
"""
@property
def tenant_key(self) -> int:
"""Get the tenant key this L2 network is assigned to."""
return int(self.get("tenant", 0))
tenant_name = Projected["str | None"](
"tenant#name as tenant_name",
str,
null=None,
doc="Get the tenant name.",
)
@property
def network_key(self) -> int:
"""Get the network key (vnet)."""
return int(self.get("vnet", 0))
network_name = Projected["str | None"](
"vnet#name as network_name",
str,
null=None,
doc="Get the network name.",
)
network_type = Projected["str | None"](
"vnet#type as network_type",
str,
null=None,
doc="Get the network type (internal, external, bgp, vpn, etc.).",
)
@property
def is_enabled(self) -> bool:
"""Check if the Layer 2 network assignment is enabled."""
return bool(self.get("enabled", False))
[docs]
def enable(self) -> TenantLayer2Network:
"""Enable this Layer 2 network assignment.
Returns:
Updated TenantLayer2Network object.
"""
from typing import cast
manager = cast("TenantLayer2Manager", self._manager)
return manager.update(self.key, enabled=True)
[docs]
def disable(self) -> TenantLayer2Network:
"""Disable this Layer 2 network assignment.
Returns:
Updated TenantLayer2Network object.
"""
from typing import cast
manager = cast("TenantLayer2Manager", self._manager)
return manager.update(self.key, enabled=False)
[docs]
def delete(self) -> None:
"""Delete this Layer 2 network assignment."""
from typing import cast
manager = cast("TenantLayer2Manager", self._manager)
manager.delete(self.key)
def __repr__(self) -> str:
enabled_str = "enabled" if self.is_enabled else "disabled"
return f"<TenantLayer2Network {self.network_name} ({enabled_str})>"
# Full default projection: the plain columns above, plus every entry the
# model declares. Adding a Projected accessor adds its field here.
TENANT_LAYER2_DEFAULT_FIELDS = [
*_TENANT_LAYER2_COLUMNS,
*TenantLayer2Network.projected_entries(),
]
[docs]
class TenantLayer2Manager(ResourceManager[TenantLayer2Network]):
"""Manager for Tenant Layer 2 Network operations.
This manager handles Layer 2 network assignments for tenants. Layer 2
networks provide bridged connectivity between parent and tenant networks,
allowing tenants direct access to parent network segments.
Only certain network types can be assigned: internal, external, bgp,
vpn, or bridged physical networks. A maximum of 28 Layer 2 networks
can be assigned per tenant.
This manager is accessed through a Tenant object's l2_networks property
or via client.tenants.l2_networks(tenant_key).
Example:
>>> tenant = client.tenants.get(name="my-tenant")
>>> # List Layer 2 networks
>>> for l2 in tenant.l2_networks.list():
... print(f"{l2.network_name}: {l2.is_enabled}")
>>> # Assign a Layer 2 network
>>> tenant.l2_networks.create(network_name="VLAN100")
"""
_endpoint = "tenant_layer2_vnets"
_default_fields = TENANT_LAYER2_DEFAULT_FIELDS
[docs]
def __init__(self, client: VergeClient, tenant: Tenant) -> None:
super().__init__(client)
self._tenant = tenant
def _to_model(self, data: dict[str, Any]) -> TenantLayer2Network:
return TenantLayer2Network(data, self)
def _scope_resource(self) -> str:
return "Tenant Layer 2 network"
def _scope_bindings(self) -> list[tuple[str, Any]]:
"""Layer 2 assignments belong to one tenant (#188)."""
return [("tenant", self._tenant.key)]
def _scope_request(self, key: int | str) -> Any:
"""Read ``tenant`` with the same collection filter ``get`` uses."""
columns = ["$key", *[column for column, _expected in self._scope_bindings()]]
params = {
"filter": f"$key eq {key}",
"fields": self._projection(columns, defaults=[]),
}
return self._client._request("GET", self._endpoint, params=params)
[docs]
def list(
self,
filter: str | None = None, # noqa: A002
fields: str | builtins.list[str] | None = None,
limit: int | None = None,
offset: int | None = None,
**kwargs: Any,
) -> builtins.list[TenantLayer2Network]:
"""List Layer 2 networks assigned to this tenant.
Args:
filter: Additional OData filter string.
fields: List of fields to return.
**kwargs: Additional filter arguments.
Returns:
List of TenantLayer2Network objects.
"""
if fields is None:
fields = self._default_fields
# Build filter for this tenant's L2 networks
tenant_filter = f"tenant eq {self._tenant.key}"
if filter:
tenant_filter = f"{tenant_filter} and ({filter})"
# Merge shorthand kwargs instead of silently dropping them (issue #96)
combined_filter = combine_filters(tenant_filter, kwargs)
params: dict[str, Any] = {
"filter": combined_filter,
"fields": self._projection(fields),
}
if limit is not None:
params["limit"] = limit
if offset is not None:
params["offset"] = offset
response = self._client._request("GET", self._endpoint, params=params)
if response is None:
return []
if not isinstance(response, list):
return [self._to_model(response)]
return [self._to_model(item) for item in response]
[docs]
def get( # type: ignore[override]
self,
key: int | None = None,
*,
network_name: str | None = None,
fields: str | builtins.list[str] | None = None,
) -> TenantLayer2Network:
"""Get a Layer 2 network by key or network name.
Args:
key: Layer 2 network assignment $key (ID).
network_name: Network name to find.
fields: List of fields to return.
Returns:
TenantLayer2Network object.
Raises:
NotFoundError: If Layer 2 network not found.
ValueError: If neither key nor network_name provided.
"""
if fields is None:
fields = self._default_fields
if key is not None:
# A key is not filtered by tenant. Ask for tenant, then refuse
# another tenant's row (#188). The collection query is what this
# endpoint returns for a single key.
params: dict[str, Any] = {
"filter": f"$key eq {key}",
"fields": self._projection(self._with_scope_fields(fields)),
}
response = self._client._request("GET", self._endpoint, params=params)
if isinstance(response, list):
response = response[0] if response else None
if not isinstance(response, dict):
from pyvergeos.exceptions import NotFoundError
raise NotFoundError(f"Tenant Layer 2 network {key} returned invalid response")
self._assert_row_in_scope(key, response)
return self._to_model(response)
if network_name is not None:
# Search by network name within this tenant's L2 networks
l2_networks = self.list(fields=fields)
for l2 in l2_networks:
if l2.network_name == network_name:
return l2
from pyvergeos.exceptions import NotFoundError
raise NotFoundError(
f"Layer 2 network '{network_name}' not found for tenant '{self._tenant.name}'"
)
raise ValueError("Either key or network_name must be provided")
[docs]
def create( # type: ignore[override]
self,
network: int | None = None,
network_name: str | None = None,
enabled: bool = True,
) -> TenantLayer2Network:
"""Assign a Layer 2 network to this tenant.
Only certain network types can be assigned as Layer 2 networks:
internal, external, bgp, vpn, or bridged physical networks.
A maximum of 28 Layer 2 networks can be assigned per tenant.
Args:
network: Network $key (ID) to assign.
network_name: Network name (alternative to network key).
enabled: Whether the assignment should be enabled (default True).
Returns:
Created TenantLayer2Network object.
Raises:
ValueError: If tenant is a snapshot or neither network nor network_name provided.
NotFoundError: If network not found.
ConflictError: If network already assigned or max limit reached.
"""
if self._tenant.is_snapshot:
raise ValueError("Cannot assign Layer 2 network to a tenant snapshot")
# Resolve network key
if network is None and network_name is None:
raise ValueError("Either network or network_name must be provided")
net_key: int
resolved_name: str | None = network_name
if network is not None:
net_key = network
else:
assert network_name is not None # Validated above.
# Look up network by name
response = self._client._request(
"GET",
"vnets",
params={"filter": f"name eq {quote_value(network_name)}", "fields": "$key,name"},
)
if not response:
from pyvergeos.exceptions import NotFoundError
raise NotFoundError(f"Network '{network_name}' not found")
net_data = response[0] if isinstance(response, list) else response
net_key = int(net_data["$key"])
body: dict[str, Any] = {
"tenant": self._tenant.key,
"vnet": net_key,
"enabled": enabled,
}
logger.debug(
f"Assigning Layer 2 network '{resolved_name or net_key}' "
f"to tenant '{self._tenant.name}'"
)
response = self._client._request("POST", self._endpoint, json_data=body)
# Get the created key from response and fetch the full object
if isinstance(response, dict) and "$key" in response:
return self.get(response["$key"])
# Fallback: fetch by network name if we have it
import time
time.sleep(0.5) # Brief wait for API consistency
if resolved_name:
return self.get(network_name=resolved_name)
# Last resort: get the most recently created L2 network for this tenant
l2_networks = self.list()
if l2_networks:
# Find the one matching our network key
for l2 in l2_networks:
if l2.network_key == net_key:
return l2
from pyvergeos.exceptions import NotFoundError
raise NotFoundError("Failed to retrieve created Layer 2 network")
[docs]
def update(self, key: int, enabled: bool) -> TenantLayer2Network: # type: ignore[override]
"""Update a Layer 2 network assignment.
Only the enabled status can be modified. To change the network
assignment, remove and recreate it.
Args:
key: Layer 2 network assignment $key (ID).
enabled: Whether the assignment should be enabled.
Returns:
Updated TenantLayer2Network object.
"""
self._ensure_in_scope(key)
body: dict[str, Any] = {"enabled": enabled}
logger.debug(f"Updating Layer 2 network {key}: enabled={enabled}")
self._client._request("PUT", f"{self._endpoint}/{key}", json_data=body)
return self.get(key)
[docs]
def delete(self, key: int) -> None:
"""Remove a Layer 2 network assignment.
Args:
key: Layer 2 network assignment $key (ID).
Warning:
Removing a Layer 2 network disconnects the bridged connectivity
between the parent and tenant networks. This may affect tenant
workloads using that network segment.
"""
self._ensure_in_scope(key)
logger.debug(f"Removing tenant Layer 2 network {key}")
self._client._request("DELETE", f"{self._endpoint}/{key}")
[docs]
def delete_by_network(self, network_name: str) -> None:
"""Remove a Layer 2 network assignment by network name.
Args:
network_name: Name of the network to remove.
Raises:
NotFoundError: If no assignment with this network exists.
"""
l2_network = self.get(network_name=network_name)
self.delete(l2_network.key)