border: NAT gateway resource (border_agent / border_node / dedicated VM)

Introduce the Border control-plane resource: a machine-managed NAT
gateway carrying its SNAT/DNAT rules inline (jsonb[]) on one flat
resource, with a PaaS builder, user API, BorderBuilder unit tests and
network.border.* permission seeds bound to project owners.

Deployment shapes, calque of net_lb.type:
* default         -> border_agent capability on the core node's agent;
* node set        -> border_node pinned to that node's agent
                     (distributed egress, e.g. a managed realm node);
* type.kind: core -> border_node on a dedicated gateway VM the iaas
                     builder provisions (net_border_iaas -> target_node_set).

The core node's agent serves only border_agent: border_node is always
pinned by the builder, and its driver ships where the data plane lives
(realm node / border VM image), mirroring paas_lb_agent vs paas_lb_node.

ec-bootstrap-templates restores /etc configs from persisted copies, so
the border additions to the universal agent template would never reach
an upgraded stand. Hoist the scheduler-section rewrite out of the
repo-proxy migration (only reachable on pre-repo-proxy stands) into
_ensure_ua_config_current(), run unconditionally on every boot: rewrite
[universal_agent_scheduler], insert BorderAgentCapabilityDriver into
caps_drivers, sync the persisted copy and try-restart the agent
services. Covered by unit tests.

Also: single 0066 init migration (final net_border schema + permission
seeds), gcl_sdk 3.1.0, drop core's own '/' static route on the shared
LB vhost, point the CLI realm endpoint docs at Core's LB.

Signed-off-by: George Melikov <mail@gmelikov.ru>

Author: gmelikov

docs/usage/local_deployment.md

@@ -126,10 +126,15 @@ field. Use this token as a `Bearer` token in all subsequent API requests.
 Configure the `exordos` CLI by registering a realm and a context with the admin credentials:
 
 ```bash
-exordos settings set-realm local --endpoint http://10.20.0.2:11010 --current
+exordos settings set-realm local --endpoint http://10.20.0.2:80/api/core --current
 exordos settings set-context local --name admin -u <ADMIN_USERNAME> -p <ADMIN_PASSWORD> --current
 ```
 
+The CLI authenticates against the `default` client alias (see above), which only Core's load
+balancer on port 80 knows how to rewrite. Pointing the realm at the node's own user-api port
+(`:11010`) instead skips the load balancer, so the alias can't be resolved and every command fails
+with `Can't parse value: uuid=default.`
+
 - `set-realm` registers the platform endpoint under the name `local` and marks it as the active realm.
 - `set-context` creates a named context with the admin credentials and marks it as the active context.
 

docs/usage/local_deployment.ru.md

@@ -126,10 +126,15 @@ curl --location 'http://10.20.0.2:80/api/core/v1/iam/clients/default/actions/get
 Настройте CLI `exordos`, зарегистрировав realm и контекст с учётными данными администратора:
 
 ```bash
-exordos settings set-realm local --endpoint http://10.20.0.2:11010 --current
+exordos settings set-realm local --endpoint http://10.20.0.2:80/api/core --current
 exordos settings set-context local --name admin -u <ADMIN_USERNAME> -p <ADMIN_PASSWORD> --current
 ```
 
+CLI аутентифицируется через алиас клиента `default` (см. выше), который умеет переписывать только
+балансировщик Core на порту 80. Если указать в качестве realm порт user-api самой ноды (`:11010`),
+балансировщик будет пропущен, алиас не резолвится, и любая команда падает с
+`Can't parse value: uuid=default.`
+
 - `set-realm` — регистрирует endpoint платформы под именем `local` и устанавливает его как активный realm.
 - `set-context` — создаёт именованный контекст с учётными данными администратора и устанавливает его как активный.
 

etc/exordos_universal_agent/exordos_universal_agent.conf.j2

@@ -17,6 +17,7 @@ caps_drivers =
     PasswordCapabilityDriver,
     CoreDNSCertificateCapabilityDriver,
     LBAgentCapabilityDriver,
+    BorderAgentCapabilityDriver,
     GuestMachineCapabilityDriver,
     SSHKeyCapabilityDriver,
     RenderAgentDriver
@@ -28,7 +29,8 @@ capabilities =
     password,
     certificate,
     paas_lb_agent,
-    repo_proxy_installed_element
+    repo_proxy_installed_element,
+    border_agent
 
 
 [CoreDNSCertificateCapabilityDriver]

exordos/manifests/core.yaml.j2

@@ -268,26 +268,6 @@ resources:
           - kind: rewrite_url
             regex: "^/api/core/v1/iam/clients/default(.*)"
             replacement: f"/v1/iam/clients/{$core.vs.variables.$iam_default_client_uuid:value}$1"
-    core_lb_static_route:
-      project_id: "12345678-c625-4fee-81d5-f691897b8142"
-      parent: $core.network.lb.$core_lb.vhosts.$core_lb_core_http:uuid
-      condition:
-        kind: prefix
-        value: /
-        allowed_ips:
-          - 0.0.0.0/0
-        modifiers:
-          - kind: auto_header
-            headers:
-              - 'Host'
-              - 'X-Forwarded-For'
-              - 'X-Forwarded-Port'
-              - 'X-Forwarded-Proto'
-              - 'X-Forwarded-Prefix'
-        actions:
-          - kind: local_dir
-            path: /var/www/html
-            is_spa: true
 
 exports:
   local_domain:

exordos_core/cmd/bootstrap.py

@@ -22,6 +22,7 @@
 import os
 import pwd
 import re
+import subprocess
 import sys
 import time
 import typing as tp
@@ -379,15 +380,10 @@ def _sync_config_to_data_path(content: str, data_path: str) -> None:
 
 
 def _migrate_installed_elements_configs() -> None:
-    """Migrate config files for repo proxy support.
+    """Migrate the core config file for repo proxy support.
 
-    Idempotently updates two config files:
-
-    1. Adds [launchpad] section to the core config file.
-    2. Adds repo_proxy_installed_element to the capabilities list
-       in the universal agent config file.
+    Idempotently adds the [launchpad] section to the core config file.
     """
-    # 1. Add [launchpad] section to the core config
     try:
         with open(CORE_CONFIG_PATH, "r", encoding="utf-8") as f:
             content = f.read()
@@ -405,45 +401,92 @@ def _migrate_installed_elements_configs() -> None:
         else:
             LOG.info("[launchpad] section already exists in %s", CORE_CONFIG_PATH)
 
-    # 2. Replace [universal_agent_scheduler] section in the UA config
-    #    to ensure repo_proxy_installed_element is present in capabilities.
-    #    The section is fully rewritten to handle any indentation differences.
-    _UA_SCHEDULER_SECTION = """\
+
+# The parts of the universal agent config that evolve with the core image.
+# The scheduler section is fully rewritten to handle any indentation
+# differences; keep both literals in sync with
+# etc/exordos_universal_agent/exordos_universal_agent.conf.j2.
+_UA_SCHEDULER_SECTION = """\
 [universal_agent_scheduler]
 capabilities =
     em_*,
     password,
     certificate,
     paas_lb_agent,
-    repo_proxy_installed_element
+    repo_proxy_installed_element,
+    border_agent
 """
+_UA_BORDER_DRIVER_LINE = "    BorderAgentCapabilityDriver,\n"
+
+
+def _ensure_ua_config_current() -> None:
+    """Bring the universal agent config up to date with this image.
+
+    ec-bootstrap-templates restores /etc configs from the persisted
+    copies on the data disk, so template changes shipped in a new core
+    image never reach an upgraded stand on their own. Idempotently
+    reapply the image-defined parts of the UA config:
+
+    1. Rewrite the [universal_agent_scheduler] section with the current
+       capabilities list.
+    2. Ensure BorderAgentCapabilityDriver is present in caps_drivers
+       ([universal_agent] holds stand-specific endpoints, so only this
+       line is inserted, not the whole section).
+
+    On changes the result is synced back to the persisted copy and the
+    agent services (started before ec-bootstrap runs, thus holding the
+    stale config) are restarted to pick it up.
+    """
     try:
         with open(UA_CONFIG_PATH, "r", encoding="utf-8") as f:
             content = f.read()
     except FileNotFoundError:
         LOG.warning("Universal agent config not found: %s", UA_CONFIG_PATH)
-    else:
-        new_content = re.sub(
-            r"^\[universal_agent_scheduler\].*?(?=^\[|\Z)",
-            _UA_SCHEDULER_SECTION,
-            content,
-            count=1,
-            flags=re.DOTALL | re.MULTILINE,
+        return
+
+    new_content = re.sub(
+        r"^\[universal_agent_scheduler\].*?(?=^\[|\Z)",
+        _UA_SCHEDULER_SECTION,
+        content,
+        count=1,
+        flags=re.DOTALL | re.MULTILINE,
+    )
+
+    if "BorderAgentCapabilityDriver" not in new_content:
+        new_content = new_content.replace(
+            "    LBAgentCapabilityDriver,\n",
+            "    LBAgentCapabilityDriver,\n" + _UA_BORDER_DRIVER_LINE,
+            1,
         )
-        if new_content != content:
-            with open(UA_CONFIG_PATH, "w", encoding="utf-8") as f:
-                f.write(new_content)
-            LOG.info(
-                "Updated [universal_agent_scheduler] section in %s",
-                UA_CONFIG_PATH,
-            )
-            _sync_config_to_data_path(new_content, UA_CONFIG_DATA_PATH)
-        else:
-            LOG.info(
-                "[universal_agent_scheduler] section already up to date in %s",
+        if "BorderAgentCapabilityDriver" not in new_content:
+            LOG.warning(
+                "Could not insert BorderAgentCapabilityDriver into caps_drivers in %s",
                 UA_CONFIG_PATH,
             )
 
+    if new_content == content:
+        LOG.info("Universal agent config already up to date in %s", UA_CONFIG_PATH)
+        return
+
+    with open(UA_CONFIG_PATH, "w", encoding="utf-8") as f:
+        f.write(new_content)
+    LOG.info("Updated universal agent config %s", UA_CONFIG_PATH)
+    _sync_config_to_data_path(new_content, UA_CONFIG_DATA_PATH)
+
+    try:
+        subprocess.run(
+            [
+                "systemctl",
+                "try-restart",
+                "exordos-universal-agent",
+                "exordos-universal-scheduler",
+            ],
+            check=True,
+        )
+        LOG.info("Restarted universal agent services to apply the new config")
+    except (OSError, subprocess.CalledProcessError) as e:
+        LOG.warning("Failed to restart universal agent services: %s", e)
+
 
 def _migrate_installed_elements_to_repo() -> None:
     """Migrate installed EM elements to repo proxy.
@@ -737,6 +780,8 @@ def main() -> None:
     # working installations are migrated.
     _migrate_installed_elements_to_repo()
 
+    _ensure_ua_config_current()
+
     if not os.path.exists(SPEC_PATH):
         LOG.info("No spec file found at %s", SPEC_PATH)
         return

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,6 +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 +126,11 @@ 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
         infra_scheduler = ua_scheduler_service.UniversalAgentSchedulerService(
@@ -228,6 +236,8 @@ 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,
             password_builder,
             em_builder,

exordos_core/network/border/__init__.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,)