From: Daniel Kral <d.kral@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [pve-devel] [PATCH docs v2 2/5] update static files to include ha rules api endpoints
Date: Fri, 20 Jun 2025 16:31:40 +0200 [thread overview]
Message-ID: <20250620143148.218469-33-d.kral@proxmox.com> (raw)
In-Reply-To: <20250620143148.218469-1-d.kral@proxmox.com>
Signed-off-by: Daniel Kral <d.kral@proxmox.com>
---
This patch is more of a show-case how the static files changed.
changes since v1:
- NEW!
api-viewer/apidata.js | 363 +++++++++++++++++++++++++++++++++++++
ha-manager.1-synopsis.adoc | 138 ++++++++++++++
2 files changed, 501 insertions(+)
diff --git a/api-viewer/apidata.js b/api-viewer/apidata.js
index 57f5942..9f0f28a 100644
--- a/api-viewer/apidata.js
+++ b/api-viewer/apidata.js
@@ -7805,6 +7805,369 @@ const apiSchema = [
"path" : "/cluster/ha/groups",
"text" : "groups"
},
+ {
+ "children" : [
+ {
+ "info" : {
+ "DELETE" : {
+ "allowtoken" : 1,
+ "description" : "Delete HA rule.",
+ "method" : "DELETE",
+ "name" : "delete_rule",
+ "parameters" : {
+ "additionalProperties" : 0,
+ "properties" : {
+ "rule" : {
+ "description" : "HA rule identifier.",
+ "format" : "pve-configid",
+ "type" : "string",
+ "typetext" : "<string>"
+ }
+ }
+ },
+ "permissions" : {
+ "check" : [
+ "perm",
+ "/",
+ [
+ "Sys.Console"
+ ]
+ ]
+ },
+ "protected" : 1,
+ "returns" : {
+ "type" : "null"
+ }
+ },
+ "GET" : {
+ "allowtoken" : 1,
+ "description" : "Read HA rule.",
+ "method" : "GET",
+ "name" : "read_rule",
+ "parameters" : {
+ "additionalProperties" : 0,
+ "properties" : {
+ "rule" : {
+ "description" : "HA rule identifier.",
+ "format" : "pve-configid",
+ "type" : "string",
+ "typetext" : "<string>"
+ }
+ }
+ },
+ "permissions" : {
+ "check" : [
+ "perm",
+ "/",
+ [
+ "Sys.Audit"
+ ]
+ ]
+ },
+ "returns" : {
+ "properties" : {
+ "rule" : {
+ "description" : "HA rule identifier.",
+ "format" : "pve-configid",
+ "type" : "string"
+ },
+ "type" : {
+ "type" : "string"
+ }
+ },
+ "type" : "object"
+ }
+ },
+ "PUT" : {
+ "allowtoken" : 1,
+ "description" : "Update HA rule.",
+ "method" : "PUT",
+ "name" : "update_rule",
+ "parameters" : {
+ "additionalProperties" : 0,
+ "properties" : {
+ "affinity" : {
+ "description" : "Describes whether the services are supposed to be kept on separate nodes, or are supposed to be kept together on the same node.",
+ "enum" : [
+ "separate",
+ "together"
+ ],
+ "instance-types" : [
+ "colocation"
+ ],
+ "optional" : 1,
+ "type" : "string",
+ "type-property" : "type"
+ },
+ "comment" : {
+ "description" : "HA rule description.",
+ "maxLength" : 4096,
+ "optional" : 1,
+ "type" : "string",
+ "typetext" : "<string>"
+ },
+ "delete" : {
+ "description" : "A list of settings you want to delete.",
+ "format" : "pve-configid-list",
+ "maxLength" : 4096,
+ "optional" : 1,
+ "type" : "string",
+ "typetext" : "<string>"
+ },
+ "digest" : {
+ "description" : "Prevent changes if current configuration file has a different digest. This can be used to prevent concurrent modifications.",
+ "maxLength" : 64,
+ "optional" : 1,
+ "type" : "string",
+ "typetext" : "<string>"
+ },
+ "nodes" : {
+ "description" : "List of cluster node names with optional priority.",
+ "format" : "pve-ha-group-node-list",
+ "instance-types" : [
+ "location"
+ ],
+ "optional" : 1,
+ "type" : "string",
+ "type-property" : "type",
+ "typetext" : "<node>[:<pri>]{,<node>[:<pri>]}*",
+ "verbose_description" : "List of cluster node members, where a priority can be given to each node. A resource bound to a group will run on the available nodes with the highest priority. If there are more nodes in the highest priority class, the services will get distributed to those nodes. The priorities have a relative meaning only. The higher the number, the higher the priority."
+ },
+ "rule" : {
+ "description" : "HA rule identifier.",
+ "format" : "pve-configid",
+ "optional" : 0,
+ "type" : "string",
+ "typetext" : "<string>"
+ },
+ "services" : {
+ "description" : "List of HA resource IDs. This consists of a list of resource types followed by a resource specific name separated with a colon (example: vm:100,ct:101).",
+ "format" : "pve-ha-resource-id-list",
+ "optional" : 1,
+ "type" : "string",
+ "typetext" : "<type>:<name>{,<type>:<name>}*"
+ },
+ "state" : {
+ "default" : "enabled",
+ "description" : "State of the HA rule.",
+ "enum" : [
+ "enabled",
+ "disabled"
+ ],
+ "optional" : 1,
+ "type" : "string"
+ },
+ "strict" : {
+ "default" : 0,
+ "description" : "Describes whether the location rule is mandatory or optional.",
+ "instance-types" : [
+ "location"
+ ],
+ "optional" : 1,
+ "type" : "boolean",
+ "type-property" : "type",
+ "typetext" : "<boolean>",
+ "verbose_description" : "Describes whether the location rule is mandatory or optional.\nA mandatory location rule makes services be restricted to the defined nodes. If none of the nodes are available, the service will be stopped.\nAn optional location rule makes services prefer to be on the defined nodes. If none of the nodes are available, the service may run on any other node."
+ },
+ "type" : {
+ "description" : "HA rule type.",
+ "enum" : [
+ "colocation",
+ "location"
+ ],
+ "type" : "string"
+ }
+ },
+ "type" : "object"
+ },
+ "permissions" : {
+ "check" : [
+ "perm",
+ "/",
+ [
+ "Sys.Console"
+ ]
+ ]
+ },
+ "protected" : 1,
+ "returns" : {
+ "type" : "null"
+ }
+ }
+ },
+ "leaf" : 1,
+ "path" : "/cluster/ha/rules/{rule}",
+ "text" : "{rule}"
+ }
+ ],
+ "info" : {
+ "GET" : {
+ "allowtoken" : 1,
+ "description" : "Get HA rules.",
+ "method" : "GET",
+ "name" : "index",
+ "parameters" : {
+ "additionalProperties" : 0,
+ "properties" : {
+ "service" : {
+ "description" : "Limit the returned list to rules affecting the specified service.",
+ "optional" : 1,
+ "type" : "string",
+ "typetext" : "<string>"
+ },
+ "state" : {
+ "description" : "Limit the returned list to the specified rule state.",
+ "enum" : [
+ "enabled",
+ "disabled"
+ ],
+ "optional" : 1,
+ "type" : "string"
+ },
+ "type" : {
+ "description" : "Limit the returned list to the specified rule type.",
+ "enum" : [
+ "colocation",
+ "location"
+ ],
+ "optional" : 1,
+ "type" : "string"
+ }
+ }
+ },
+ "permissions" : {
+ "check" : [
+ "perm",
+ "/",
+ [
+ "Sys.Audit"
+ ]
+ ]
+ },
+ "returns" : {
+ "items" : {
+ "links" : [
+ {
+ "href" : "{rule}",
+ "rel" : "child"
+ }
+ ],
+ "properties" : {
+ "rule" : {
+ "type" : "string"
+ }
+ },
+ "type" : "object"
+ },
+ "type" : "array"
+ }
+ },
+ "POST" : {
+ "allowtoken" : 1,
+ "description" : "Create HA rule.",
+ "method" : "POST",
+ "name" : "create_rule",
+ "parameters" : {
+ "additionalProperties" : 0,
+ "properties" : {
+ "affinity" : {
+ "description" : "Describes whether the services are supposed to be kept on separate nodes, or are supposed to be kept together on the same node.",
+ "enum" : [
+ "separate",
+ "together"
+ ],
+ "instance-types" : [
+ "colocation"
+ ],
+ "optional" : 1,
+ "type" : "string",
+ "type-property" : "type"
+ },
+ "comment" : {
+ "description" : "HA rule description.",
+ "maxLength" : 4096,
+ "optional" : 1,
+ "type" : "string",
+ "typetext" : "<string>"
+ },
+ "nodes" : {
+ "description" : "List of cluster node names with optional priority.",
+ "format" : "pve-ha-group-node-list",
+ "instance-types" : [
+ "location"
+ ],
+ "optional" : 1,
+ "type" : "string",
+ "type-property" : "type",
+ "typetext" : "<node>[:<pri>]{,<node>[:<pri>]}*",
+ "verbose_description" : "List of cluster node members, where a priority can be given to each node. A resource bound to a group will run on the available nodes with the highest priority. If there are more nodes in the highest priority class, the services will get distributed to those nodes. The priorities have a relative meaning only. The higher the number, the higher the priority."
+ },
+ "rule" : {
+ "description" : "HA rule identifier.",
+ "format" : "pve-configid",
+ "optional" : 0,
+ "type" : "string",
+ "typetext" : "<string>"
+ },
+ "services" : {
+ "description" : "List of HA resource IDs. This consists of a list of resource types followed by a resource specific name separated with a colon (example: vm:100,ct:101).",
+ "format" : "pve-ha-resource-id-list",
+ "optional" : 0,
+ "type" : "string",
+ "typetext" : "<type>:<name>{,<type>:<name>}*"
+ },
+ "state" : {
+ "default" : "enabled",
+ "description" : "State of the HA rule.",
+ "enum" : [
+ "enabled",
+ "disabled"
+ ],
+ "optional" : 1,
+ "type" : "string"
+ },
+ "strict" : {
+ "default" : 0,
+ "description" : "Describes whether the location rule is mandatory or optional.",
+ "instance-types" : [
+ "location"
+ ],
+ "optional" : 1,
+ "type" : "boolean",
+ "type-property" : "type",
+ "typetext" : "<boolean>",
+ "verbose_description" : "Describes whether the location rule is mandatory or optional.\nA mandatory location rule makes services be restricted to the defined nodes. If none of the nodes are available, the service will be stopped.\nAn optional location rule makes services prefer to be on the defined nodes. If none of the nodes are available, the service may run on any other node."
+ },
+ "type" : {
+ "description" : "HA rule type.",
+ "enum" : [
+ "colocation",
+ "location"
+ ],
+ "type" : "string"
+ }
+ },
+ "type" : "object"
+ },
+ "permissions" : {
+ "check" : [
+ "perm",
+ "/",
+ [
+ "Sys.Console"
+ ]
+ ]
+ },
+ "protected" : 1,
+ "returns" : {
+ "type" : "null"
+ }
+ }
+ },
+ "leaf" : 0,
+ "path" : "/cluster/ha/rules",
+ "text" : "rules"
+ },
{
"children" : [
{
diff --git a/ha-manager.1-synopsis.adoc b/ha-manager.1-synopsis.adoc
index 0e4c5ab..540c7ca 100644
--- a/ha-manager.1-synopsis.adoc
+++ b/ha-manager.1-synopsis.adoc
@@ -193,6 +193,144 @@ Delete resource configuration.
HA resource ID. This consists of a resource type followed by a resource specific name, separated with colon (example: vm:100 / ct:100). For virtual machines and containers, you can simply use the VM or CT id as a shortcut (example: 100).
+*ha-manager rules add* `<type> <rule> --services <string>` `[OPTIONS]`
+
+Create HA rule.
+
+`<type>`: `<colocation | location>` ::
+
+HA rule type.
+
+`<rule>`: `<string>` ::
+
+HA rule identifier.
+
+`--comment` `<string>` ::
+
+HA rule description.
+
+`--services` `<type>:<name>{,<type>:<name>}*` ::
+
+List of HA resource IDs. This consists of a list of resource types followed by a resource specific name separated with a colon (example: vm:100,ct:101).
+
+`--state` `<disabled | enabled>` ('default =' `enabled`)::
+
+State of the HA rule.
+
+
+
+
+`Conditional options:`
+
+`[type=colocation]` ;;
+
+`--affinity` `<separate | together>` ::
+
+Describes whether the services are supposed to be kept on separate nodes, or are supposed to be kept together on the same node.
+
+`[type=location]` ;;
+
+`--nodes` `<node>[:<pri>]{,<node>[:<pri>]}*` ::
+
+List of cluster node names with optional priority.
+
+`--strict` `<boolean>` ('default =' `0`)::
+
+Describes whether the location rule is mandatory or optional.
+
+*ha-manager rules config* `[OPTIONS]` `[FORMAT_OPTIONS]`
+
+Get HA rules.
+
+`--service` `<string>` ::
+
+Limit the returned list to rules affecting the specified service.
+
+`--state` `<disabled | enabled>` ::
+
+Limit the returned list to the specified rule state.
+
+`--type` `<colocation | location>` ::
+
+Limit the returned list to the specified rule type.
+
+*ha-manager rules list* `[OPTIONS]` `[FORMAT_OPTIONS]`
+
+Get HA rules.
+
+`--service` `<string>` ::
+
+Limit the returned list to rules affecting the specified service.
+
+`--state` `<disabled | enabled>` ::
+
+Limit the returned list to the specified rule state.
+
+`--type` `<colocation | location>` ::
+
+Limit the returned list to the specified rule type.
+
+*ha-manager rules remove* `<rule>`
+
+Delete HA rule.
+
+`<rule>`: `<string>` ::
+
+HA rule identifier.
+
+*ha-manager rules set* `<type> <rule>` `[OPTIONS]`
+
+Update HA rule.
+
+`<type>`: `<colocation | location>` ::
+
+HA rule type.
+
+`<rule>`: `<string>` ::
+
+HA rule identifier.
+
+`--comment` `<string>` ::
+
+HA rule description.
+
+`--delete` `<string>` ::
+
+A list of settings you want to delete.
+
+`--digest` `<string>` ::
+
+Prevent changes if current configuration file has a different digest. This can be used to prevent concurrent modifications.
+
+`--services` `<type>:<name>{,<type>:<name>}*` ::
+
+List of HA resource IDs. This consists of a list of resource types followed by a resource specific name separated with a colon (example: vm:100,ct:101).
+
+`--state` `<disabled | enabled>` ('default =' `enabled`)::
+
+State of the HA rule.
+
+
+
+
+`Conditional options:`
+
+`[type=colocation]` ;;
+
+`--affinity` `<separate | together>` ::
+
+Describes whether the services are supposed to be kept on separate nodes, or are supposed to be kept together on the same node.
+
+`[type=location]` ;;
+
+`--nodes` `<node>[:<pri>]{,<node>[:<pri>]}*` ::
+
+List of cluster node names with optional priority.
+
+`--strict` `<boolean>` ('default =' `0`)::
+
+Describes whether the location rule is mandatory or optional.
+
*ha-manager set* `<sid>` `[OPTIONS]`
Update resource configuration.
--
2.39.5
_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
next prev parent reply other threads:[~2025-06-20 14:35 UTC|newest]
Thread overview: 70+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-06-20 14:31 [pve-devel] [RFC common/cluster/ha-manager/docs/manager v2 00/40] HA colocation rules Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH common v2 1/1] introduce HashTools module Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH cluster v2 1/3] cfs: add 'ha/rules.cfg' to observed files Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH cluster v2 2/3] datacenter config: make pve-ha-shutdown-policy optional Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH cluster v2 3/3] datacenter config: introduce feature flag for location rules Daniel Kral
2025-06-23 15:58 ` Thomas Lamprecht
2025-06-24 7:29 ` Daniel Kral
2025-06-24 7:51 ` Thomas Lamprecht
2025-06-24 8:19 ` Daniel Kral
2025-06-24 8:25 ` Thomas Lamprecht
2025-06-24 8:52 ` Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 01/26] tree-wide: make arguments for select_service_node explicit Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 02/26] manager: improve signature of select_service_node Daniel Kral
2025-06-23 16:21 ` Thomas Lamprecht
2025-06-24 8:06 ` Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 03/26] introduce rules base plugin Daniel Kral
2025-07-04 14:18 ` Michael Köppl
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 04/26] rules: introduce location rule plugin Daniel Kral
2025-06-20 16:17 ` Jillian Morgan
2025-06-20 16:30 ` Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 05/26] rules: introduce colocation " Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 06/26] rules: add global checks between location and colocation rules Daniel Kral
2025-07-01 11:02 ` Daniel Kral
2025-07-04 14:43 ` Michael Köppl
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 07/26] config, env, hw: add rules read and parse methods Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 08/26] manager: read and update rules config Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 09/26] test: ha tester: add test cases for future location rules Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 10/26] resources: introduce failback property in service config Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 11/26] manager: migrate ha groups to location rules in-memory Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 12/26] manager: apply location rules when selecting service nodes Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 13/26] usage: add information about a service's assigned nodes Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 14/26] manager: apply colocation rules when selecting service nodes Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 15/26] manager: handle migrations for colocated services Daniel Kral
2025-06-27 9:10 ` Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 16/26] sim: resources: add option to limit start and migrate tries to node Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 17/26] test: ha tester: add test cases for strict negative colocation rules Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 18/26] test: ha tester: add test cases for strict positive " Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 19/26] test: ha tester: add test cases in more complex scenarios Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 20/26] test: add test cases for rules config Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 21/26] manager: handle negative colocations with too many services Daniel Kral
2025-07-01 12:11 ` Michael Köppl
2025-07-01 12:23 ` Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 22/26] config: prune services from rules if services are deleted from config Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 23/26] api: introduce ha rules api endpoints Daniel Kral
2025-07-04 14:16 ` Michael Köppl
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 24/26] cli: expose ha rules api endpoints to ha-manager cli Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 25/26] api: groups, services: assert use-location-rules feature flag Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH ha-manager v2 26/26] api: services: check for colocations for service motions Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH docs v2 1/5] ha: config: add section about ha rules Daniel Kral
2025-06-20 14:31 ` Daniel Kral [this message]
2025-06-20 14:31 ` [pve-devel] [PATCH docs v2 3/5] update static files to include use-location-rules feature flag Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH docs v2 4/5] update static files to include ha resources failback flag Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH docs v2 5/5] update static files to include ha service motion return value schema Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH manager v2 1/5] api: ha: add ha rules api endpoints Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH manager v2 2/5] ui: add use-location-rules feature flag Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH manager v2 3/5] ui: ha: hide ha groups if use-location-rules is enabled Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH manager v2 4/5] ui: ha: adapt resources components " Daniel Kral
2025-06-20 14:31 ` [pve-devel] [PATCH manager v2 5/5] ui: ha: add ha rules components and menu entry Daniel Kral
2025-06-30 15:09 ` Michael Köppl
2025-07-01 14:38 ` Michael Köppl
2025-06-20 15:43 ` [pve-devel] [RFC common/cluster/ha-manager/docs/manager v2 00/40] HA colocation rules Daniel Kral
2025-06-20 17:11 ` Jillian Morgan
2025-06-20 17:45 ` DERUMIER, Alexandre via pve-devel
[not found] ` <476c41123dced9d560dfbf27640ef8705fd90f11.camel@groupe-cyllene.com>
2025-06-23 15:36 ` Thomas Lamprecht
2025-06-24 8:48 ` Daniel Kral
2025-06-27 12:23 ` Friedrich Weber
2025-06-27 12:41 ` Daniel Kral
2025-06-23 8:11 ` DERUMIER, Alexandre via pve-devel
[not found] ` <bf973ec4e8c52a10535ed35ad64bf0ec8d1ad37d.camel@groupe-cyllene.com>
2025-06-23 15:28 ` Thomas Lamprecht
2025-06-23 23:21 ` DERUMIER, Alexandre via pve-devel
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20250620143148.218469-33-d.kral@proxmox.com \
--to=d.kral@proxmox.com \
--cc=pve-devel@lists.proxmox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal