border: dedicated VM gateway via type: core

Give Border a type discriminator like the LB (core_agent default | core),
calque of net_lb.type. type: core provisions a dedicated small VM gateway
(BorderIaasBuilder -> target_node_set from [gservice] border_image); the
paas builder then schedules the border_node capability onto that VM's
agent. An explicit node pin still wins over type. Adds migration 0068
(type jsonb + ipsv4 varchar[]), ipsv4 read-only in the API, and tests.

For small installations that want a produced gateway VM instead of turning
the core node into the NAT gateway (core_agent) or pinning to a compute
node (border_node).

Author: gmelikov

exordos_core/cmd/gservice.py

@@ -34,6 +34,15 @@
         default="https://repo.exordos.com/exordos-lbaas/0.1.0/exordos-lbaas.raw.zst",
         help="URL to get image for LB dataplane VM",
     ),
+    cfg.StrOpt(
+        "border-image",
+        default=(
+            "https://repo.exordos.com/exordos-border/0.1.0/exordos-border.raw.zst"
+        ),
+        help="URL to get the image for a `core` (VM-based) border gateway. "
+        "The image must ship the universal agent with "
+        "BorderCapabilityDriver (border_node capability).",
+    ),
 ]
 
 

exordos_core/gservice/service.py

@@ -48,7 +48,9 @@
 from exordos_core.elements.services import builders as em_builders
 from exordos_core.janitor import service as janitor_service
 from exordos_core.network import service as n_network_service
+from exordos_core.network.border.builders import iaas as net_border_iaas
 from exordos_core.network.border.builders import paas as net_border_paas
+from exordos_core.network.border.dm import models as border_models
 from exordos_core.network.lb.builders import iaas as net_lb_iaas
 from exordos_core.network.lb.builders import paas as net_lb_paas
 from exordos_core.network.lb.dm import models as lb_models
@@ -123,6 +125,10 @@ def __init__(self, iter_min_period=3, iter_pause=0.1):
             project_id=nc.NODE_SET_PROJECT,
         )
         net_lb_paas_builder = net_lb_paas.LBBuilder()
+        net_border_iaas_builder = net_border_iaas.BorderIaasBuilder(
+            instance_model=border_models.IaasBorder,
+            project_id=nc.NODE_SET_PROJECT,
+        )
         net_border_paas_builder = net_border_paas.BorderBuilder()
 
         # Infra scheduler
@@ -226,6 +232,7 @@ def __init__(self, iter_min_period=3, iter_pause=0.1):
             service_builder,
             net_lb_iaas_builder,
             net_lb_paas_builder,
+            net_border_iaas_builder,
             net_border_paas_builder,
             secret_svc,
             em_builder,

exordos_core/network/border/builders/iaas.py

@@ -0,0 +1,110 @@
+#    Copyright 2026 Genesis Corporation.
+#
+#    All Rights Reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+import logging
+import typing as tp
+import uuid as sys_uuid
+
+from gcl_sdk.agents.universal.dm import models as ua_models
+from gcl_sdk.infra import constants as sdk_c
+from gcl_sdk.infra.dm import models as sdk_models
+from gcl_sdk.infra.services import builder
+from oslo_config import cfg
+
+from exordos_core.network.border.dm import models
+from exordos_core.network.lb.dm import models as lb_models
+
+LOG = logging.getLogger(__name__)
+CONF = cfg.CONF
+
+NODE_SET_KIND = lb_models.TargetNodeSet.get_resource_kind()
+
+
+class BorderIaasBuilder(builder.CoreInfraBuilder):
+    """Provisions the dedicated VM of a `core` (VM-based) border.
+
+    Calque of the LB iaas builder: one single-replica target_node_set from
+    ``[gservice] border_image`` (an image whose universal agent ships
+    BorderCapabilityDriver). The paas builder schedules the ``border_node``
+    capability onto that VM's agent, same as it does for a pinned node.
+    """
+
+    _name_prefix = "border"
+
+    def __init__(
+        self,
+        instance_model: tp.Type[models.IaasBorder],
+        project_id: sys_uuid.UUID,
+    ):
+        super().__init__(instance_model)
+        self._project_id = project_id
+
+    def create_infra(
+        self, instance: models.IaasBorder
+    ) -> tp.Collection[ua_models.TargetResourceKindAwareMixin]:
+        # A pinned border (node set) never provisions its own VM,
+        # whatever the type says.
+        if instance.node or instance.type.kind != "core":
+            return []
+
+        node_set = lb_models.TargetNodeSet(
+            uuid=instance.uuid,
+            name=f"{self._name_prefix}-{instance.name}",
+            cores=instance.type.cpu,
+            ram=instance.type.ram,
+            replicas=1,
+            project_id=self._project_id,
+            status=sdk_c.NodeStatus.NEW.value,
+            disk_spec=sdk_models.SetRootDiskSpec(
+                size=instance.type.disk_size,
+                image=CONF.gservice.border_image,
+            ),
+        )
+        return [node_set]
+
+    def actualize_infra(
+        self,
+        instance: models.IaasBorder,
+        infra: builder.InfraCollection,
+    ) -> tp.Collection[ua_models.TargetResourceKindAwareMixin]:
+        if instance.node or instance.type.kind != "core":
+            return tuple()
+
+        nodeset = None
+        tgt_nodeset = None
+        for target, actual in infra.infra_objects:
+            if target.get_resource_kind() == NODE_SET_KIND:
+                nodeset = actual
+                target.cores = instance.type.cpu
+                target.ram = instance.type.ram
+                target.replicas = 1
+                tgt_nodeset = target
+                break
+        else:
+            raise ValueError("A core border must have its target_node_set!")
+
+        if nodeset and nodeset.nodes:
+            instance.ipsv4 = [node["ipv4"] for node in nodeset.nodes.values()]
+
+        # The paas builder owns the final ACTIVE/ERROR flip (it tracks the
+        # border_node capability); here only reflect VM provisioning.
+        try:
+            if sdk_c.InstanceStatus(nodeset.status) == sdk_c.InstanceStatus.ERROR:
+                instance.status = sdk_c.InstanceStatus.ERROR.value
+        except (ValueError, AttributeError):
+            pass
+
+        return (tgt_nodeset,)

exordos_core/network/border/builders/paas.py

@@ -16,15 +16,22 @@
 
 import logging
 import typing as tp
+import uuid as sys_uuid
 
 from gcl_sdk.agents.universal.dm import models as ua_models
+from gcl_sdk.infra.dm import models as sdk_models
 from gcl_sdk.paas.services import builder
+from restalchemy.dm import filters as ra_filters
+from restalchemy.storage import exceptions as ra_storage_exc
 
 from exordos_core.elements import constants as cc
 from exordos_core.network.border.dm import models
+from exordos_core.network.lb.dm import models as lb_models
 
 LOG = logging.getLogger(__name__)
 
+NODE_SET_KIND = lb_models.TargetNodeSet.get_resource_kind()
+
 
 class BorderBuilder(builder.PaaSBuilder):
     def __init__(
@@ -45,12 +52,14 @@ def actualize_paas_objects(
         instance: models.PaasBorder,
         paas_collection: builder.PaaSCollection,
     ) -> tp.Collection[ua_models.TargetResourceKindAwareMixin]:
-        """Produce a single border capability resource.
+        """Produce the border capability resource(s).
 
-        With ``instance.node`` set it is a ``border_node`` scheduled to that
-        node's agent (distributed egress, e.g. a managed realm node);
-        otherwise a ``border_agent`` scheduled by capability to the core
-        node's agent (step 0).
+        Deployment shape precedence (see the user_api Border model):
+        * ``instance.node``   -> ``border_node`` pinned to that node's agent
+          (distributed egress, e.g. a managed realm node);
+        * ``type.kind: core`` -> ``border_node`` on the dedicated VM the iaas
+          builder provisions (net_border_iaas -> target_node_set);
+        * otherwise           -> ``border_agent`` on the core node (step 0).
         """
 
         if instance.node:
@@ -63,6 +72,19 @@ def actualize_paas_objects(
                     routes=instance.get_routes(),
                 )
             ]
+        elif instance.type.kind == "core":
+            # Until the iaas builder has the VM up there is nothing to
+            # schedule; the instance stays IN_PROGRESS and is retried.
+            actual_resources = [
+                models.BorderNode(
+                    uuid=sys_uuid.UUID(node_uuid),
+                    agent_uuid=sys_uuid.UUID(node_uuid),
+                    snat_rules=instance.get_snat_rules(),
+                    forwards=instance.get_forwards(),
+                    routes=instance.get_routes(),
+                )
+                for node_uuid in self._get_iaas_nodes(instance)
+            ]
         else:
             actual_resources = [
                 models.BorderAgent(
@@ -87,3 +109,17 @@ def actualize_paas_objects(
             instance.status = cc.ServiceStatus.IN_PROGRESS.value
 
         return actual_resources
+
+    def _get_iaas_nodes(self, instance: models.PaasBorder) -> tp.List[str]:
+        """Node uuids of the border VM node set (empty until provisioned)."""
+        try:
+            res = ua_models.Resource.objects.get_one(
+                filters={
+                    "uuid": ra_filters.EQ(instance.uuid),
+                    "kind": ra_filters.EQ(NODE_SET_KIND),
+                }
+            )
+        except ra_storage_exc.RecordNotFound:
+            return []
+        nodeset = sdk_models.NodeSet.from_ua_resource(res)
+        return list(nodeset.nodes or {})

exordos_core/network/border/dm/models.py

@@ -19,6 +19,7 @@
 from restalchemy.dm import properties
 from restalchemy.dm import types
 
+from exordos_core.network.lb.dm import models as lb_models
 from exordos_core.user_api.network.dm import models
 
 
@@ -65,6 +66,33 @@ def get_resource_kind(cls) -> str:
         return "border_node"
 
 
+class IaasBorder(models.Border, ua_models.InstanceWithDerivativesMixin):
+    """IaaS view of a `core` (dedicated VM) border.
+
+    Mirrors IaasLB: for type.kind == "core" the iaas builder materializes a
+    single-replica target_node_set (the gateway VM); the paas builder then
+    schedules the border_node capability to that VM's agent.
+    """
+
+    __derivative_model_map__ = {
+        "target_node_set": lb_models.TargetNodeSet,
+    }
+
+    @classmethod
+    def get_resource_kind(cls) -> str:
+        return "net_border_iaas"
+
+    def get_resource_target_fields(self):
+        return frozenset(
+            (
+                "uuid",
+                "name",
+                "type",
+                "project_id",
+            )
+        )
+
+
 class PaasBorder(models.Border, ua_models.InstanceWithDerivativesMixin):
     __derivative_model_map__ = {
         "border_agent": BorderAgent,
@@ -82,6 +110,7 @@ def get_resource_target_fields(self):
                 "name",
                 "project_id",
                 "node",
+                "type",
             )
         )
 

exordos_core/tests/unit/network/test_border_builder.py

@@ -47,10 +47,11 @@ def test_paasborder_getters_read_inline_rules():
     assert border.get_routes() == []
 
 
-def _instance(snat=None, forwards=None, routes=None, node=None):
+def _instance(snat=None, forwards=None, routes=None, node=None, kind="core_agent"):
     inst = mock.MagicMock()
     inst.uuid = sys_uuid.uuid4()
     inst.node = node
+    inst.type.kind = kind
     inst.get_snat_rules.return_value = snat or []
     inst.get_forwards.return_value = forwards or []
     inst.get_routes.return_value = routes or []
@@ -120,6 +121,81 @@ def test_produces_border_node_when_target_node_set():
     assert node_res.forwards == forwards
 
 
+def test_core_kind_schedules_border_node_per_vm_node():
+    vm_node = sys_uuid.uuid4()
+    snat = [{"source_cidr": "10.77.0.0/24", "mode": "masquerade", "snat_to": None}]
+    inst = _instance(snat=snat, kind="core")
+
+    b = border_paas.BorderBuilder()
+    with mock.patch.object(b, "_get_iaas_nodes", return_value=[str(vm_node)]):
+        resources = b.create_paas_objects(inst)
+
+    assert len(resources) == 1
+    node_res = resources[0]
+    assert node_res.get_resource_kind() == "border_node"
+    # The capability lands on the dedicated VM's agent.
+    assert node_res.uuid == vm_node
+    assert node_res.agent_uuid == vm_node
+    assert node_res.snat_rules == snat
+
+
+def test_core_kind_defers_until_the_vm_exists():
+    inst = _instance(kind="core")
+
+    b = border_paas.BorderBuilder()
+    with mock.patch.object(b, "_get_iaas_nodes", return_value=[]):
+        resources = b.create_paas_objects(inst)
+
+    assert resources == []
+    assert inst.status == cc.ServiceStatus.IN_PROGRESS.value
+
+
+def test_pinned_node_wins_over_core_kind():
+    node = sys_uuid.uuid4()
+    inst = _instance(node=node, kind="core")
+
+    resources = border_paas.BorderBuilder().create_paas_objects(inst)
+
+    assert len(resources) == 1
+    assert resources[0].get_resource_kind() == "border_node"
+    assert resources[0].agent_uuid == node
+
+
+def test_iaas_builder_provisions_single_vm_for_core_kind():
+    from oslo_config import cfg
+
+    from exordos_core.network.border.builders import iaas as border_iaas
+
+    try:
+        cfg.CONF.register_opts(
+            [cfg.StrOpt("border_image", default="http://img/border.raw.zst")],
+            "gservice",
+        )
+    except cfg.DuplicateOptError:
+        pass
+
+    inst = _instance(kind="core")
+    inst.name = "gw"
+    inst.type.cpu = 2
+    inst.type.ram = 1024
+    inst.type.disk_size = 12
+
+    b = border_iaas.BorderIaasBuilder.__new__(border_iaas.BorderIaasBuilder)
+    b._project_id = sys_uuid.uuid4()
+
+    objs = b.create_infra(inst)
+    assert len(objs) == 1
+    ns = objs[0]
+    assert ns.get_resource_kind() == "target_node_set"
+    assert ns.replicas == 1
+    assert ns.cores == 2 and ns.ram == 1024
+    assert ns.disk_spec.image.endswith("border.raw.zst")
+
+    # core_agent and pinned borders never provision a VM
+    assert b.create_infra(_instance(kind="core_agent")) == []
+    assert b.create_infra(_instance(kind="core", node=sys_uuid.uuid4())) == []
+
+
 def test_status_in_progress_when_no_actual_objects_yet():
     inst = _instance()
     border_paas.BorderBuilder().actualize_paas_objects(inst, _collection())

exordos_core/user_api/network/api/controllers.py

@@ -127,6 +127,7 @@ class BorderController(
             default=field_p.Permissions.RW,
             fields={
                 "status": {constants.ALL: field_p.Permissions.RO},
+                "ipsv4": {constants.ALL: field_p.Permissions.RO},
             },
         ),
     )