Architecture

This document describes the architecture of the Inmanta Connect module: how services are structured, how they decompose into network segments, and how multi-vendor support is achieved.

Service Hierarchy

Connect defines a layered service model where higher-level services build on lower-level ones:

• Infrastructure defines the physical network: devices, network elements, and ports.

• UNI (User Network Interface) represents customer attachment points on the network, referencing one or more ports.

• L2 Connect, L3 VPN, and DIA are connectivity services that terminate on UNIs.

• Carrier Ethernet EVC provides a MEF-compliant wrapper around L2 connectivity.

Each service is managed through Inmanta’s Lifecycle Service Manager (LSM), with its own configurable state machine governing create, update, delete, and maintenance operations.

Segment Decomposition

The core architectural pattern in Connect is segment decomposition. Rather than treating an end-to-end connection as a monolithic configuration, the service is broken down into typed segments that each represent a distinct section of the network path.

How It Works

When an L2 Connect service is created between two UNIs, the allocation phase determines the network path and decomposes it into segments:

Each segment:

• Has a type that determines the technology used (VPLS, VPWS, ring, bridge, link, PON)

• Contains one or more network elements (devices) that participate in the segment

• Has interfaces on each network element that need to be configured

• Is connected to adjacent segments through shared nodes

Segment Types

Type	Description	Typical Use
vpls	Multi-point Layer 2 service over IP/MPLS using LDP or EVPN	Core network multipoint
vpws	Point-to-point Layer 2 service over IP/MPLS using LDP or EVPN	Core network point-to-point
ring	Devices connected in a ring topology; all devices on the ring are configured for each service	Access/aggregation rings
bridge	Single device acting as a Layer 2 bridge	CPE switches, access devices
link	Unmanaged physical connection between two endpoints (e.g., a cable)	Direct physical links
pon	Passive Optical Network segment with OLT and ONT devices	Fiber access networks

Nodes: Stitching Segments Together

Nodes are the glue between segments. A node groups the interfaces from two adjacent segments (or from a segment and an endpoint) that share a common point in the network. This ensures VLAN continuity across segment boundaries.

Each node has:

• A VLAN allocation (outer VLAN and optional inner VLAN for Q-in-Q)

• An encapsulation type (dot1q, qinq, or untagged)

• References to all interfaces at that junction point

The constraint is simple: every interface in the same node must use the same VLAN encapsulation, ensuring end-to-end connectivity.

Segment Continuity Rules

1. Each interface on a network element in a segment belongs to exactly one node.

2. Each node connects either two different segments (a junction) or a segment and an endpoint (a termination).

3. VLAN allocations within a node are consistent across all interfaces.

Multi-Vendor Abstraction

Connect supports multiple network vendors through a provider pattern that separates service definition from device configuration.

How It Works

1. Service entities (Connection, L3VPN, DIA, etc.) define the service in vendor-neutral terms.

2. Provider entities implement vendor-specific configuration for each service type.

3. Conditional implementations select the correct provider based on the device_kind of each network element.

For example, when an L2 Connect segment of type vpls includes a Nokia device, the Nokia VPLS implementation is automatically selected. If the same segment includes a Juniper device, the Juniper VPLS implementation is used for that device. This allows a single service to span multiple vendors transparently.

Supported Device Kinds

Device Kind	Vendor	Protocol
nokia-sros	Nokia SR-OS	NETCONF
nokia-srlinux	Nokia SR Linux	gNMI
cisco-xr	Cisco IOS-XR	NETCONF
cisco-xe	Cisco IOS-XE	NETCONF
juniper-mx	Juniper MX	NETCONF
mikrotik	MikroTik	RouterOS
tibit-olt	Tibit OLT	REST
tibit-ont	Tibit ONT	REST
snmp	Generic SNMP	SNMP

Resource Management

Each vendor implementation manages two categories of resources:

• Shared resources (co-managed): Physical interface configuration, device-level settings. These are shared across multiple services and use comanaged=true to allow concurrent management.

• Service resources (exclusive): Service-specific configuration like VLAN sub-interfaces, VPN instances, QoS policies. These use comanaged=false and are fully owned by a single service instance.

When a service is deleted, its exclusive resources are purged while shared resources remain for other services.

Allocation System

Services require unique identifiers (service IDs, VLANs, route targets, etc.) that must be allocated before configuration can be pushed to devices. Connect supports three allocation modes:

• Built-in allocation: Connect manages a configured range of identifiers and allocates from it. This is the default mode and requires no external dependencies.

• Inventory-based allocation: An external inventory system (e.g., NetBox, FNT) is responsible for allocating identifiers. Connect queries the inventory during the allocation phase.

• External API allocation: A custom allocator plugin calls an external API to obtain identifiers, enabling integration with any third-party system.

The table below lists the identifiers that need to be allocated and their default built-in configuration keys:

Identifier	Scope	Configuration Key
Service ID	Per service type	carrier_ethernet_evc.service_id
VLAN	Per node	Allocated per node from VLAN pool
EVI	Per EVPN segment	l2_connect.evi
Route Target	Per EVPN segment	l2_connect.route_target
Route Dist.	Per NE in segment	l2_connect.route_distinguisher
RD/RT	Per L3VPN	l3vpn.rd_number, l3vpn.rt_number
LAG ID	Per multi-homed UNI	uni.lag_id_range
P2P Network	Per DIA/L3VPN EP	direct_internet_access.p2p_networks

When using built-in allocation, ranges are configured in connect-config.yaml. The allocation strategy can be next (sequential) or any (random). When using inventory or external API allocation, these ranges are not needed as the external system is the source of truth.

Configuration System

Connect’s behavior is driven by a YAML configuration file (connect-config.yaml) that controls:

• Allocation ranges for service IDs, VLANs, EVIs, route targets, etc.

• Naming templates (Jinja2) for service names, interface descriptions, SAP IDs, etc.

• Vendor-specific settings like QoS policies, NETCONF retry parameters, BGP filters, etc.

• Feature toggles for multi-homing, Ethernet CFM, link-local addressing, etc.

• Inventory configuration including resolver selection and inventory paths.

• Lifecycle configuration per service type (which operations are enabled).

Templates use the template:// prefix to reference Jinja2 files in the module or project, allowing full customization of naming conventions without modifying the module code. See the Configuration section for details.

Inventory Integration

Connect uses a pluggable inventory system to resolve UNI references to physical network resources. Three resolvers are available:

• Inmanta (built-in): Resolves UNIs from a local YAML file (connect-inventory.yaml).

• NetBox: Resolves UNIs from a NetBox instance via its REST API.

• FNT: Resolves UNIs from an FNT Command inventory.

The inventory provides:

1. UNI resolution: Maps abstract UNI references to physical ports, devices, and management details.

2. Identifier allocation: Optionally allocates VLANs, service IDs, and other identifiers from external systems.

3. Service documentation: Records provisioned services back into the inventory.

See the Inventory section for details.

Lifecycle Management

Each service type has its own configurable state machine built using the LifecycleFactory. The factory supports:

• Create/Delete: Basic service provisioning and teardown.

• Update: Modify service parameters in-place.

• Repair: Re-deploy the desired state to fix drift.

• Maintenance: Put a service into maintenance mode.

• Compliance reporting: Detect and report configuration drift.

• Deletion validation: Check for dependent services before allowing deletion.

• Forced deletion: Bypass validation for emergency cleanup.

The state machine transitions are:

Each state can have in-progress and failed sub-states, and the lifecycle can be customized per service type through the configuration file.

Compliance Reporting

Connect supports compliance reporting on all service types (requires LSM 4+ / ISO 9+). Each service extends CompliantServiceEntity, which enables the LSM framework to track whether the deployed configuration on network devices matches the desired state.

How it works:

After a service reaches the up state, the LSM framework periodically checks the compliance of all resources belonging to that service. If a resource is found to have drifted from its desired state, the service transitions to up_non_compliant (shown with a warning label in the UI).

Recovery paths from up_non_compliant:

• Automatic recovery: The framework re-checks compliance and transitions the service back to up if the drift is resolved.

• Repair: If repair is enabled on the lifecycle, an operator can trigger a repair operation that re-deploys the desired configuration to the device.

The same compliance mechanism also applies during the onboarding phase, using a parallel set of onboarding_non_compliant states.

On older LSM versions (< 4), the compliance states are automatically omitted from the state machine, so the feature degrades gracefully.

Onboarding Existing Services

Connect supports onboarding services that already exist on the network but are not yet managed by the orchestrator. This is useful when adopting Connect on a brownfield network where services have been provisioned manually or by another system.

Onboarding is enabled per service type via the with_onboarding flag in the lifecycle configuration. When enabled, services can be created with onboarding_start as an alternative initial state instead of the normal creating flow.

How it works:

1. Validation: The service is created in onboarding_start. Connect validates the service attributes against the existing network state. If validation fails, the service moves to onboarding_rejected where the operator can correct the attributes and retry, or cancel.

2. Compliance check: Once validated, the service enters onboarding_inprogress. Connect deploys its desired state in fail mode (no changes are pushed to devices) and checks whether the existing device configuration matches. If compliant, the service moves to onboarding_done.

3. Promotion to up: From onboarding_done, the service automatically promotes to up and enters normal lifecycle management.

Recovery paths during onboarding:

• Create missing resources: If the existing configuration is incomplete, an operator can trigger a transition to creating which will push the missing configuration to devices.

• Delete: If the onboarded service should be removed, it can be transitioned to deleting to clean up both the service instance and the device configuration.

• Cancel: The onboarding can be cancelled without affecting the network by transitioning to terminated.