Doc for network extension (#649)

* Doc for network extension

* Update doc: use JSON payload

Author: weizhouapache

source/adminguide/extensions.rst

@@ -17,7 +17,7 @@
 Extensions
 ==========
 
-Extensions are a new mechanism introduced in Apache CloudStack to allow administrators to extend the platform's functionality by integrating external systems or custom workflows. Currently, CloudStack supports a single extension type called Orchestrator.
+Extensions are a new mechanism introduced in Apache CloudStack to allow administrators to extend the platform's functionality by integrating external systems or custom workflows. Currently, CloudStack supports two extension types: Orchestrator and NetworkOrchestrator.
 
 In the UI, extensions can be managed under *Extensions* menu.
 
@@ -26,7 +26,7 @@ In the UI, extensions can be managed under *Extensions* menu.
 Overview
 ^^^^^^^^
 
-An extension in CloudStack is defined as an external binary (written in any programming language) that implements specific actions CloudStack can invoke. This allows operators to manage resource lifecycle operations outside CloudStack, such as provisioning VMs in third-party systems or triggering external automation pipelines.
+An extension in CloudStack is defined as an external binary (written in any programming language) that implements specific actions CloudStack can invoke. This allows operators to manage resource lifecycle operations outside CloudStack, such as provisioning VMs in third-party systems, orchestrating network and VPC services on external devices, or triggering external automation pipelines.
 
 Extensions are managed through the API and UI, with support for configuration, resource mappings, and action execution.
 
@@ -41,7 +41,7 @@ Administrators can define and manage the following components of an extension:
 
    - Configuration Details: Key-value properties used by the extension at runtime.
 
-   - Resource Mappings: Association between extensions and CloudStack resources such as clusters, etc.
+   - Resource Mappings: Association between extensions and CloudStack resources such as clusters and physical networks.
 
 Path and Availabilty
 ^^^^^^^^^^^^^^^^^^^^
@@ -80,6 +80,25 @@ An Orchestrator extension enables CloudStack to delegate VM orchestration to an
 
    |extension.png|
 
+NetworkOrchestrator Extension
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A NetworkOrchestrator extension enables CloudStack to delegate guest network and VPC service orchestration to an external network system. Key features include:
+
+    - Physical Network Mapping: NetworkOrchestrator extensions are registered with a CloudStack physical network instead of a cluster.
+
+    - Provider-based Integration: When a NetworkOrchestrator extension is registered with a physical network, CloudStack creates an external network service provider using the extension name. Network and VPC offerings can then use that provider.
+
+    - Capability-driven Services: Supported services are declared through the extension details ``network.services`` and optional per-service capabilities in ``network.service.capabilities``. CloudStack uses these declarations when exposing supported services and validating offering capabilities.
+
+    - Network and VPC Lifecycle: Depending on the declared services, the extension can handle operations for guest networks, VPCs, public IPs, NAT, load balancing, DHCP, DNS, userdata, network ACLs, and related restart or reapply flows.
+
+    - Registration Details: Resource-specific details such as device endpoints, credentials, host lists, or interface mappings can be stored on the physical-network registration and updated later through the UI or the ``updateRegisteredExtension`` API.
+
+    - Network and VPC Custom Actions: Admins can define custom actions for ``Network`` and ``Vpc`` resources when the extension advertises the ``CustomAction`` service.
+
+    - Reference Implementation: A Linux network namespace based implementation is available in `cloudstack-extensions <https://github.com/apache/cloudstack-extensions/tree/network-namespace/Network-Namespace>`_. This reference backend has been validated with KVM-based smoke tests.
+
 
 CloudStack provides built-in Orchestrator Extensions for Proxmox, Hyper-V, and MaaS, which work with their respective environments out of the box.
 

source/adminguide/extensions/custom_actions.rst

@@ -17,7 +17,9 @@
 Custom Actions
 ^^^^^^^^^^^^^^
 
-In addition to standard instance operations, extensions support custom actions. These can be configured via UI in the extension details view or the addCustomAction API. The extension binary or script must implement handlers for these action names and process any provided parameters.
+In addition to standard lifecycle operations, extensions support custom actions. These can be configured via UI in the extension details view or the addCustomAction API. The extension binary or script must implement handlers for these action names and process any provided parameters.
+
+For Orchestrator extensions, custom actions typically target ``VirtualMachine`` resources. For NetworkOrchestrator extensions, custom actions can target ``Network`` and ``Vpc`` resources when the extension advertises the ``CustomAction`` network service.
 
    |add-custom-action.png|
 
@@ -43,11 +45,34 @@ A single parameter can have the following details:
 
    - **valueoptions**: Options for the value of the parameter. This is allowed only for NUMBER and STRING type.
 
+Supported Resource Types
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Custom actions can be attached to the following resource types:
+
+   - ``VirtualMachine`` for Orchestrator extensions.
+
+   - ``Network`` for NetworkOrchestrator extensions.
+
+   - ``Vpc`` for NetworkOrchestrator extensions.
+
+For network and VPC custom actions, CloudStack dispatches the action to the external provider that serves the ``CustomAction`` service for the selected resource.
+
+For ``NetworkOrchestrator`` extensions, the action is executed as ``custom-action`` using the standard payload-file invocation model:
+
+.. code-block:: bash
+
+   /path/to/<extension_name>.sh custom-action <payload_file> <timeout_seconds>
+
+The payload file contains top-level keys such as ``action``, ``action-params``, ``physical-network-extension-details``, and ``network-extension-details``. Unlike other network extension commands, the custom action request does not wrap its command-specific values inside a nested ``payload`` object.
+
 
 Running Custom Action
 ~~~~~~~~~~~~~~~~~~~~~
 
-All enabled custom actions can then be triggered for a resource of the type the action is defined for or provided while running, using the **Run Action** view or runCustomAction API.
+All enabled custom actions can then be triggered for a resource of the type the action is defined for or provided while running, using the **Run Action** view or the relevant custom action API.
+
+For network and VPC custom actions, CloudStack passes the full request in the payload file and returns the script's ``stdout`` to the caller. The available actions shown in the UI depend on the selected resource type and the extension bound to that resource.
 
    |run-custom-action-instance.png|