[WFCORE-6960]: Promote Simple config export for a server as an attachment from COMMUNITY to DEFAULT.

core/WFCORE-6960_Simple_config_export_for_a_server_as_an_attachment_for_standalone_or_domain_mode.adoc

@@ -0,0 +1,174 @@
+---
+categories:
+ - core
+ - management
+---
+= [Community] Simple config export for a server as an attachment for standalone or domain mode 
+:author:            Emmanuel Hugonnet
+:email:             [email protected]
+:toc:               left
+:icons:             font
+:idprefix:
+:idseparator:       -
+:keywords:          management,core,configuration
+
+== Overview
+
+The purpose of this feature is to enrich the management model with a new operation *read-config-as-xml-file* equivalent to the existing *read-config-as-xml* that would return a stream to be either displayed or saved to a file.
+
+== Issue Metadata
+
+=== Issue
+
+* https://issues.redhat.com/browse/WFCORE-6960[WFCORE-6960]
+
+=== Related Issues
+
+* https://issues.redhat.com/browse/WFCORE-4758[WFCORE-4758]
+* https://issues.redhat.com/browse/EAP7-1810[EAP7-1810]
+
+=== Stability Level
+// Choose the planned stability level for the proposed functionality
+* [ ] Experimental
+
+* [ ] Preview
+
+* [ ] Community
+
+* [X] default
+
+=== Dev Contacts
+
+* mailto:{email}[{author}]
+
+=== QE Contacts
+
+* mailto:[email protected][Fabio Burzigotti]
+
+=== 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
+* [X] Engineering
+
+* [ ] QE
+
+=== Affected Projects or Components
+
+* HAL
+
+=== Other Interested Projects
+
+=== 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
+
+Enrich the management model with a new operation *read-config-as-xml-file* equivalent to the existing *read-config-as-xml* that would return a stream to be either displayed or saved to a file on the machine where the JBoss CLI is running on.
+This operation should replace the existing '*read-config-as-xml*' operation without the escaping issues in the long term.
+It should work for a standalone server as for a domain server.
+
+=== Hard Requirements
+
+ * Export the current running configuration as an XML data stream that can be saved or displayed with the attachment operation from the CLI.
+ * Since the full configuration is read, the operation should fail if the user is not in a role that allows reading sensitive data.
+ * Make this feature a DEFAULT feature.
+ * The stream can be saved on the computer where the jboss-cli is running from.
+
+=== Nice-to-Have Requirements
+
+=== Non-Requirements
+
+== Backwards Compatibility
+
+This new feature provides the same functionnality as previously but with a different command:
+Instead of :
+----
+[standalone@localhost:9990 /] :read-config-as-xml
+<?xml version='1.0' encoding='UTF-8'?>
+...
+----
+
+one should now use:
+----
+[standalone@localhost:9990 /] attachment display --operation=:read-config-as-xml-file
+ATTACHMENT 3363018e-1a79-401a-a865-97d85c83f5f4:
+<?xml version='1.0' encoding='UTF-8'?>
+...
+----
+
+=== Default Configuration
+
+N/A
+
+=== Importing Existing Configuration
+
+N/A
+
+=== Deployments
+
+N/A
+
+== Implementation Plan
+
+* Create a new management operation that takes the result of the marshalling done in *read-config-as-xml* and but returns it as a stream instead of a String.
+
+=== Usage examples
+
+Simple usage:
+----
+[standalone@localhost:9990 /] :read-config-as-xml-file
+{
+"outcome" => "success",
+"result" => {"uuid" => "89c858bf-dba4-4d38-8b8c-93e13beaacca"},
+"response-headers" => {"attached-streams" => [{
+"uuid" => "89c858bf-dba4-4d38-8b8c-93e13beaacca",
+"mime-type" => "application/xml"
+}]}
+}
+----
+
+To display the content of the file:
+----
+[standalone@localhost:9990 /] attachment display --operation=:read-config-as-xml-file
+ATTACHMENT 3363018e-1a79-401a-a865-97d85c83f5f4:
+<?xml version='1.0' encoding='UTF-8'?>
+...
+----
+
+To save the content of the file:
+----
+[standalone@localhost:9990 /] attachment save --operation=:read-config-as-xml-file --file=/home/wildfly/tmp/standalone-runtime.xml
+File saved to /home/wildfly/tmp/standalone-runtime.xml
+----
+
+== Test Plan
+
+* Add a test "testReadConfigAsXmlFile" into the class `org.wildfly.core.test.standalone.mgmt.api.CoreServerTestCase` in the standalone testsuite to check that the result of the operation is the same as the "standalone.xml" file used to start the server.
+
+* Add several tests to the class `org.jboss.as.test.integration.domain.suites.ManagementReadXmlAsFileTestCase` in the domain testsuite:
+    ** testDomainReadConfigAsXmlFile: check that the result of the operation is the same as the "domain-standard.xml" file used to start the server.
+    ** testDomainReadConfigAsXmlFileWithCli: check that the result of the operation is the same as the "domain-standard.xml" file used to start the server using the CLI.
+    ** testHostReadConfigAsXmlFile: check that the result of the operation is the same as the "host-master.xml" and "host-slave.xml" files used to start the hosts.
+    ** testHostReadConfigAsXmlFileWithCli: check that the result of the operation is the same as the "host-master.xml" and "host-slave.xml" files used to start the hosts using the CLI.
+    ** testServerReadConfigAsXmlFile: check that the result of the operation is the configuration expected in the "main-one.xml" and "main-three.xml" files.
+    ** testServerReadConfigAsXmlFileWithCli: check that the result of the operation is the configuration expected in the "main-one.xml" and "main-three.xml" files using the CLI.
+
+* Add a test to the class `org.jboss.as.test.integration.mgmt.access.StandardRolesBasicTestCase` in the rbac testsuite:
+    ** readWholeConfigAsXMLFile
+
+== Community Documentation
+
+* Covered by operation description in management model.
+* Covered by updates to the WildFly community documentation in CLI Recipes, see https://github.com/wildfly/wildfly/pull/18159
+
+== Release Note Content
+
+A new operation to export the effective configuration of a server as an XML file on the machine where the JBoss CLI is running.