feature: extensions

For apache/cloudstack#9752

Signed-off-by: Abhishek Kumar <[email protected]>

Author: shwstppr

source/_static/images/add-custom-action.png

@@ -0,0 +1,124 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information#
+   regarding copyright ownership.  The ASF licenses this file
+   to you 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.
+   
+
+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.
+
+In the UI, extensions can be managed under *Extensions* menu.
+
+   |extensions.png|
+
+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.
+
+Extensions are managed through the API and UI, with support for configuration, resource mappings, and action execution.
+
+   |create-extension.png|
+
+Configuration
+~~~~~~~~~~~~~
+
+Administrators can define and manage the following components of an extension:
+
+   - Entry Point: A file or script that will be executed during extension operations.
+
+   - Configuration Details: Key-value properties used by the extension at runtime.
+
+   - Resource Mappings: Association between extensions and CloudStack resources such as clusters, etc.
+
+Entry Point
+~~~~~~~~~~~
+
+The entry point for an extension can be any binary or executable script. If no explicit entry point is provided, CloudStack uses a default base Bash script. The state of the entry point is validated across all management servers. In the UI, the Entry Point State is displayed as Not Ready if the file is missing, inaccessible, or differs across management servers.
+
+All extension entry point files are stored under a directory named after the extension within `/usr/share/cloudstack-management/extensions`.
+
+Payload
+~~~~~~~
+
+CloudStack sends structured JSON payloads to the extension binary during each operation. These payloads are written to .json files stored under `/var/lib/cloudstack/management/extensions`. The extension binary is expected to read the file and return an appropriate result. CloudStack automatically attempts to clean up payload files older than one day.
+
+
+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 entry-point must implement handlers for these action names and process any provided parameters.
+
+   |add-custom-action.png|
+
+Description, allowed role types, parameters, success/error messages, configuration details, timeout can be defined during creation or update.
+Alowed role types can be one or more of Admin, Resource Admin, Domain Admin, User.
+Success and error messages will be used and returned during action execution. They allow string expansion and the following can be used to customise messgaes:
+
+   - {{actionName}} for showing name of the action
+   - {{extensionName}} for showing name of the extension
+   - {{resourceName}} for showing name of the resource.
+
+An example usage can be - "Successfully completed {{actionName}} for {{resourceName}} using {{extensionName}}".
+Configuration details can be key-value pairs which will be passed to the extension entry-point during action execution.
+Timeout value can be configured to adjust wait time for action completion.
+
+A single parameter can have the following details:
+
+   - **name**: Name of the parameter.
+
+   - **type**: Type of the parameter. It can be one of the following: BOOLEAN, DATE, NUMBER, STRING
+
+   - **validationformat**: Validation format for the parameter value. Supported only for NUMBER and STRING type. For NUMBER, it can be NONE or DECIMAL. For STRING, it can be NONE, EMAIL, PASSWORD, URL, UUID.
+
+   - **valueoptions**: Options for the value of the parameter. This is allowed only for NUMBER and STRING type.
+
+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.
+
+   |run-custom-action.png|
+
+Orchestrator Extension
+----------------------
+
+An Orchestrator extension enables CloudStack to delegate VM orchestration to an external system. Key features include:
+
+   - Cluster Mapping: Orchestrator extensions can be associated with one or more CloudStack clusters.
+
+   - Hosts: Multiple hosts can be added to such clusters, ideally pointing to different physical or external hosts.
+
+   - Instance Lifecycle Support: Extensions can handle basic VM actions like prepare, deploy, start, stop, reboot, status and delete.
+
+   - Configuration Details: Key-value configuration details can be specified at different levels - extension, cluster mapping, host, template, service offering, instance.
+
+   - Custom Actions: Admins can define custom actions beyond the standard VM operations.
+
+
+   |run-custom-action.png|
+
+
+CloudStack provides sample built-in orchestrator extensions for demonstration and testing purposes.
+
+
+.. Images
+
+
+.. |extensions.png| image:: /_static/images/extensions.png
+.. |create-extension.png| image:: /_static/images/create-extension.png
+.. |add-custom-action.png| image:: /_static/images/add-custom-action.png
+.. |run-custom-action.png| image:: /_static/images/run-custom-action.png
+.. |run-custom-action-instance.png| image:: /_static/images/run-custom-action-instance.png