Skip to content

Commit a099564

Browse files
shwstpprshwstppr
committed
more details
Signed-off-by: Abhishek Kumar <[email protected]>
1 parent 201e195 commit a099564

File tree

3 files changed

+133
-40
lines changed

3 files changed

+133
-40
lines changed

‎source/adminguide/extensions.rst‎

Lines changed: 3 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -55,43 +55,6 @@ Payload
5555

5656
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.
5757

58-
59-
Custom Actions
60-
~~~~~~~~~~~~~~
61-
62-
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.
63-
64-
|add-custom-action.png|
65-
66-
Description, allowed role types, parameters, success/error messages, configuration details, timeout can be defined during creation or update.
67-
Alowed role types can be one or more of Admin, Resource Admin, Domain Admin, User.
68-
Success and error messages will be used and returned during action execution. They allow string expansion and the following can be used to customise messages:
69-
70-
- {{actionName}} for showing name of the action
71-
- {{extensionName}} for showing name of the extension
72-
- {{resourceName}} for showing name of the resource
73-
74-
An example usage can be - "Successfully completed {{actionName}} for {{resourceName}} using {{extensionName}}".
75-
Configuration details can be key-value pairs which will be passed to the extension entry-point during action execution.
76-
Timeout value can be configured to adjust wait time for action completion.
77-
78-
A single parameter can have the following details:
79-
80-
- **name**: Name of the parameter.
81-
82-
- **type**: Type of the parameter. It can be one of the following: BOOLEAN, DATE, NUMBER, STRING
83-
84-
- **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.
85-
86-
- **valueoptions**: Options for the value of the parameter. This is allowed only for NUMBER and STRING type.
87-
88-
Running Custom Action
89-
---------------------
90-
91-
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.
92-
93-
|run-custom-action.png|
94-
9558
Orchestrator Extension
9659
----------------------
9760

@@ -115,12 +78,12 @@ An Orchestrator extension enables CloudStack to delegate VM orchestration to an
11578

11679
CloudStack provides sample built-in orchestrator extensions for demonstration and testing purposes.
11780

81+
.. include:: extensions/custom_actions.rst
82+
83+
.. include:: extensions/troubleshooting.rst
11884

11985
.. Images
12086
12187
12288
.. |extensions.png| image:: /_static/images/extensions.png
12389
.. |create-extension.png| image:: /_static/images/create-extension.png
124-
.. |add-custom-action.png| image:: /_static/images/add-custom-action.png
125-
.. |run-custom-action.png| image:: /_static/images/run-custom-action.png
126-
.. |run-custom-action-instance.png| image:: /_static/images/run-custom-action-instance.png

‎source/adminguide/extensions/custom_actions.rst‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
.. Licensed to the Apache Software Foundation (ASF) under one
2+
or more contributor license agreements. See the NOTICE file
3+
distributed with this work for additional information#
4+
regarding copyright ownership. The ASF licenses this file
5+
to you under the Apache License, Version 2.0 (the
6+
"License"); you may not use this file except in compliance
7+
with the License. You may obtain a copy of the License at
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
Unless required by applicable law or agreed to in writing,
10+
software distributed under the License is distributed on an
11+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
12+
KIND, either express or implied. See the License for the
13+
specific language governing permissions and limitations
14+
under the License.
15+
16+
17+
Custom Actions
18+
~~~~~~~~~~~~~~
19+
20+
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.
21+
22+
|add-custom-action.png|
23+
24+
Description, allowed role types, parameters, success/error messages, configuration details, timeout can be defined during creation or update.
25+
Alowed role types can be one or more of Admin, Resource Admin, Domain Admin, User.
26+
Success and error messages will be used and returned during action execution. They allow string expansion and the following can be used to customise messages:
27+
28+
- {{actionName}} for showing name of the action
29+
- {{extensionName}} for showing name of the extension
30+
- {{resourceName}} for showing name of the resource
31+
32+
An example usage can be - "Successfully completed {{actionName}} for {{resourceName}} using {{extensionName}}".
33+
Configuration details can be key-value pairs which will be passed to the extension entry-point during action execution.
34+
Timeout value can be configured to adjust wait time for action completion.
35+
36+
A single parameter can have the following details:
37+
38+
- **name**: Name of the parameter.
39+
40+
- **type**: Type of the parameter. It can be one of the following: BOOLEAN, DATE, NUMBER, STRING
41+
42+
- **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.
43+
44+
- **valueoptions**: Options for the value of the parameter. This is allowed only for NUMBER and STRING type.
45+
46+
Running Custom Action
47+
---------------------
48+
49+
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.
50+
51+
|run-custom-action.png|
52+
53+
54+
.. Images
55+
56+
57+
.. |add-custom-action.png| image:: /_static/images/add-custom-action.png
58+
.. |run-custom-action.png| image:: /_static/images/run-custom-action.png
59+
.. |run-custom-action-instance.png| image:: /_static/images/run-custom-action-instance.png

‎source/adminguide/extensions/troubleshooting.rst‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
.. Licensed to the Apache Software Foundation (ASF) under one
2+
or more contributor license agreements. See the NOTICE file
3+
distributed with this work for additional information#
4+
regarding copyright ownership. The ASF licenses this file
5+
to you under the Apache License, Version 2.0 (the
6+
"License"); you may not use this file except in compliance
7+
with the License. You may obtain a copy of the License at
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
Unless required by applicable law or agreed to in writing,
10+
software distributed under the License is distributed on an
11+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
12+
KIND, either express or implied. See the License for the
13+
specific language governing permissions and limitations
14+
under the License.
15+
16+
17+
Troubleshooting Extensions
18+
~~~~~~~~~~~~~~~~~~~~~~~~~~
19+
20+
Validate the Extension Entry Point
21+
----------------------------------
22+
23+
- Ensure that the entry point path is correctly defined and accessible on all management servers.
24+
25+
- The script or binary must be executable and have appropriate permissions.
26+
27+
- If the binary differs across management servers, the extension will be marked as Not Ready.
28+
29+
- Entry points are stored at: `/usr/share/cloudstack-management/extensions/<extension_name>`
30+
31+
- CloudStack runs a background task at regular intervals to verify entry point readiness. If the entry point is not ready, its state will appear as Not Ready in the UI or API responses.
32+
33+
- Alerts are generated if an entry point is persistently not ready.
34+
35+
- The check interval can be configured using the cloudstack.extensions.entrypoint.check.interval property in global.properties. The default is 5 minutes.
36+
37+
Verify Payload Handling
38+
-----------------------
39+
40+
- Ensure the extension binary can correctly read and parse the incoming JSON payload.
41+
42+
- Payload files are placed at: `/var/lib/cloudstack/management/extensions/<extension_name>/`
43+
44+
- These payload files are automatically cleaned up after 24 hours.
45+
46+
- Improper parsing of the payload is a common cause of failure—log any parsing errors in your extension binary for debugging.
47+
48+
Refer to Base Extension Scripts
49+
-------------------------------
50+
51+
- For guidance on implementing supported actions, refer to the base scripts present for each extension type.
52+
53+
- For Orchestrator-type extensions, see: `/usr/share/cloudstack-common/scripts/vm/hypervisor/external/provisioner/provisioner.sh`
54+
55+
- These scripts provide examples of how to handle standard actions like start, stop, status, etc.
56+
57+
Check Logs for Errors
58+
---------------------
59+
60+
- If the extension does not respond or returns an error, check the management server logs.
61+
62+
- Logs include details of:
63+
64+
1. Invocation of the extension binary
65+
66+
2. Payload hand-off
67+
68+
3. Output parsing
69+
70+
- Any exceptions or exit code issues.
71+

0 commit comments

Comments
 (0)