From 8cb6c781a973e9b33a15f46b559578bab913a05b Mon Sep 17 00:00:00 2001 From: Darran Lofthouse Date: Fri, 6 Sep 2024 17:40:30 +0100 Subject: [PATCH 1/4] [WFCORE-6830] New attributes on the HTTP Management Interface to configure resource constraints. --- ...-6830_Management_Resource_Constraints.adoc | 221 ++++++++++++++++++ 1 file changed, 221 insertions(+) create mode 100644 management/WFCORE-6830_Management_Resource_Constraints.adoc diff --git a/management/WFCORE-6830_Management_Resource_Constraints.adoc b/management/WFCORE-6830_Management_Resource_Constraints.adoc new file mode 100644 index 00000000..d000ca0e --- /dev/null +++ b/management/WFCORE-6830_Management_Resource_Constraints.adoc @@ -0,0 +1,221 @@ +--- +categories: + - management +--- += [Community] [WFCORE-6830] Additional management attributes to contrain HTTP management interface resource utilisation. +:author: Darran Lofthouse +:email: darran.lofthouse@jboss.org +:toc: left +:icons: font +:idprefix: +:idseparator: - + +== Overview + +Previously under https://issues.redhat.com/browse/WFCORE-6825[WFCORE-6825] an update was made to the HTTP management interface +to allow the following system properties to be set to configure the constraints applied to the HTTP management interface: + + * `org.wildfly.management.backlog` + * `org.wildfly.management.connection-high-water` + * `org.wildfly.management.connection-low-water` + * `org.wildfly.management.no-request-timeout` + + If the system properties were not set these would defalt to: + + * backlog = 50 + * connection-high-water = 100 + * connection-low-water = 75 + * no-request-timeout = 60000 + +This proposal is to add attributes to the management model for the HTTP management interface at the "Community" stability level +to enable these to be configured directly in the management model. + +== Issue Metadata + +=== Issue + +* https://issues.redhat.com/browse/WFCORE-6830[WFCORE-6830] + +=== Related Issues + +* https://issues.redhat.com/browse/WFCORE-6825[WFCORE-6825] - The original issue to add the system properties. +* https://issues.redhat.com/browse/WFCORE-6829[WFCORE-6829] - A new community level schema for the core management model. +* https://issues.redhat.com/browse/WFLY-19715[WFLY-19715] - Task to document the new attributes. + +=== Stability Level +// Choose the planned stability level for the proposed functionality +* [ ] Experimental + +* [ ] Preview + +* [*] Community + +* [ ] default + +=== Dev Contacts + +* mailto:{email}[{author}] + +=== QE Contacts + +=== Testing By +// Put an x in the relevant field to indicate if testing will be done by Engineering or QE. +// Discuss with QE during the Kickoff state to decide this +* [*] Engineering + +* [ ] QE + +=== Affected Projects or Components + +* WildFly Core +* WildFly + +=== Other Interested Projects + +The https://github.com/wildfly-extras/creaper[Creaper] project is also impacted by the changes as adding a community +level schema impacts version detection in this project as reported under +https://github.com/wildfly-extras/creaper/issues/236[Issue#236]. + +=== Relevant Installation Types +// Remove the x next to the relevant field if the feature in question is not relevant +// to that kind of WildFly installation +* [x] Traditional standalone server (unzipped or provisioned by Galleon) + +* [x] Managed domain + +* [x] OpenShift s2i + +* [x] Bootable jar + +== Requirements + +=== Hard Requirements + +Four new attributes will be added to the HTTP management interface to configure the supported resource constraints that +can be applied: + + * `backlog` + * `connection-high-water` + * `connection-low-water` + * `no-request-timeout` + + The resulting resource will look like: + +[source] +---- + /core-service=management/management-interface=http-interface:read-resource(include-defaults=true) +{ + "outcome" => "success", + "result" => { + "allowed-origins" => undefined, + "backlog" => 50, + "connection-high-water" => 100, + "connection-low-water" => 75, + "console-enabled" => true, + "constant-headers" => undefined, + "http-authentication-factory" => "management-http-authentication", + "http-upgrade" => { + "enabled" => true, + "sasl-authentication-factory" => "management-sasl-authentication" + }, + "http-upgrade-enabled" => true, + "no-request-timeout" => 60000, + "sasl-protocol" => "remote", + "secure-socket-binding" => undefined, + "server-name" => undefined, + "socket-binding" => "management-http", + "ssl-context" => undefined + } +} +---- + +When persisted to the configuration file the resulting XML will look like: + +[source,xml] +---- + + + + + + + +---- + +=== Nice-to-Have Requirements + +None + +=== Non-Requirements + +The purpose of this feature request is to expose management model attributes to configure existing behaviour within the +application server, this feature request is not intended to revisit the existing behaviour which is already available at +all stability levels. + +=== Future Work + +The only possible future work could be to promote one or all of these new attributes to a higher stability level. + +A change such as this should likely be constrained to: + + * Removing the stability level qualifier from the attribute definitions allowing them to be used at the default stability level. + * Moving the XML schema definitions and parsing to an appropriate schema at the default stability level. + +== Backwards Compatibility + +In considering backwards compatibility if an attribute is defined on the HTTP management interface AND the +corresponding system property is set then the system property should take precedence. + +=== Default Configuration + +The new attributes will not be present in the default configuration, instead the default values will remain in use. + +=== Importing Existing Configuration + +As the attributes are optional and defined with default values the changes here will not impact the ability to import +and existing configuration. + +=== Deployments + +N/A + +=== Interoperability + +N/A + +== Security Considerations + +Security constraints are already defined on the management interfaces, these new attributes do not require further constraints. + +== Test Plan + +The original issue https://issues.redhat.com/browse/WFCORE-6825[WFCORE-6825] already added a test case to the `manualmode` +testsuite `org.wildfly.core.test.standalone.mgmt.ManagementInterfaceResourcesTestCase`, this test uses the system properties +to define the resource constraints and then checks that the constraints are applied. This test will be enhanced so that in +addition to the testing it performs using system properties the same tests are repeated setting the constraints as attributes +in the management model. + +WildFly Core also contains two test cases which test the parsing and marshalling of the management model from XML and back +for the management interfaces: + + * `org.jboss.as.core.model.test.mgmt_interfaces.StandaloneMgmtInterfacesTestCase` + * `org.jboss.as.core.model.test.mgmt_interfaces.HostMgmtInterfacesTestCase` + +These test cases will both have a test added to parse and marshall a configuration with all of the new attributes defined. + +== Community Documentation + +Under https://issues.redhat.com/browse/WFLY-19715[WFLY-19715] documented will be added describing the new attributes +and how they can be used. + +== Release Note Content + +Previously under https://issues.redhat.com/browse/WFCORE-6825[WFCORE-6825] four system properties with default values were +added to enable the constraints affecting the HTTP management interface to be configured. Under +https://issues.redhat.com/browse/WFCORE-6830[WFCORE-6830] four new attributes have been added to the HTTP management interface +(`backlog`, `connection-high-water`, `connection-low-water`, `no-request-timeout`) to allow these constraints to be configured +directly in the management model. + +These new attributes are available for servers running at the `Community` stability level or lower. From 9a18514dd81c0181b6b282b87316d4e0819093a1 Mon Sep 17 00:00:00 2001 From: Darran Lofthouse Date: Sun, 15 Sep 2024 12:36:04 +0100 Subject: [PATCH 2/4] [WFCORE-6830] Add information about the admin clients to the proposal. --- ...FCORE-6830_Management_Resource_Constraints.adoc | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/management/WFCORE-6830_Management_Resource_Constraints.adoc b/management/WFCORE-6830_Management_Resource_Constraints.adoc index d000ca0e..b2970272 100644 --- a/management/WFCORE-6830_Management_Resource_Constraints.adoc +++ b/management/WFCORE-6830_Management_Resource_Constraints.adoc @@ -185,6 +185,20 @@ N/A N/A +== Admin Clients + +The JBoss CLI utilises low level management operations when updating the http-management-interface, these dynamically +take into account the results of calling :read-resource-description so these new attributes will be automatically +supported by the CLI when the server is running at the `Community` stability level or lower. + +The admin console does contain a screen dedicated to the management of the HTTP management interface available at +http://localhost:9990/console/index.html#standalone-server[HTTP Management Interface]. This screen is dynamically rendered +based on the attributes defined on the HTTP management interface resource, this means that when the server is running at +a stability level that supports these new attributes the admin console will automatically support them - in other cases they +will not be present in the view. + +No follow up tasks are required for either admin client. + == Security Considerations Security constraints are already defined on the management interfaces, these new attributes do not require further constraints. From 8511a65b68da8422ab1bbaabd12db0cfac7ad997 Mon Sep 17 00:00:00 2001 From: Darran Lofthouse Date: Sun, 15 Sep 2024 14:59:44 +0100 Subject: [PATCH 3/4] [WFCORE-6830] Small update to specify that a deprecation message will be output. Also include an example of the output message. --- .../WFCORE-6830_Management_Resource_Constraints.adoc | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/management/WFCORE-6830_Management_Resource_Constraints.adoc b/management/WFCORE-6830_Management_Resource_Constraints.adoc index b2970272..1afeccbf 100644 --- a/management/WFCORE-6830_Management_Resource_Constraints.adoc +++ b/management/WFCORE-6830_Management_Resource_Constraints.adoc @@ -20,7 +20,7 @@ to allow the following system properties to be set to configure the constraints * `org.wildfly.management.connection-low-water` * `org.wildfly.management.no-request-timeout` - If the system properties were not set these would defalt to: + If the system properties were not set these would default to: * backlog = 50 * connection-high-water = 100 @@ -168,6 +168,16 @@ A change such as this should likely be constrained to: In considering backwards compatibility if an attribute is defined on the HTTP management interface AND the corresponding system property is set then the system property should take precedence. +For each of the system properties if defined and if the attribute is supported at the current stability level a message in the +following format will be logged to inform the administrator that they should move to using the new attribute definitions. + +[source] +---- +14:58:13,878 INFO [org.jboss.as.controller.management-deprecated] (Controller Boot Thread) WFLYCTL0515: The system +property 'org.wildfly.management.backlog' is deprecated and may be removed in a future version, attribute 'backlog' on +resource '/core-service=management/management-interface=http-interface' should be used instead. +---- + === Default Configuration The new attributes will not be present in the default configuration, instead the default values will remain in use. From 6672457b1dda882cbadf71d374950fa33a4caa6f Mon Sep 17 00:00:00 2001 From: Darran Lofthouse Date: Sun, 15 Sep 2024 17:57:22 +0100 Subject: [PATCH 4/4] [WFCORE-6830] Add some additional information about the community documentation. --- management/WFCORE-6830_Management_Resource_Constraints.adoc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/management/WFCORE-6830_Management_Resource_Constraints.adoc b/management/WFCORE-6830_Management_Resource_Constraints.adoc index 1afeccbf..ea210267 100644 --- a/management/WFCORE-6830_Management_Resource_Constraints.adoc +++ b/management/WFCORE-6830_Management_Resource_Constraints.adoc @@ -162,6 +162,8 @@ A change such as this should likely be constrained to: * Removing the stability level qualifier from the attribute definitions allowing them to be used at the default stability level. * Moving the XML schema definitions and parsing to an appropriate schema at the default stability level. + * The community documentation can be simplified to remove references to the stability level + `Community` once supported at all stability levels. == Backwards Compatibility @@ -234,6 +236,10 @@ These test cases will both have a test added to parse and marshall a configurati Under https://issues.redhat.com/browse/WFLY-19715[WFLY-19715] documented will be added describing the new attributes and how they can be used. +The documentation will also clarify that the default values are still applicable when +running at the stability level of `Default` and include information about the system +properties that can be used. + == Release Note Content Previously under https://issues.redhat.com/browse/WFCORE-6825[WFCORE-6825] four system properties with default values were