IGNITE-24430 Added documentation about migration of the control utili…

…ty to the thin client protocol (#11856) Co-authored-by: SofiaSedova <[email protected]> (cherry picked from commit d25afae)
apache · Feb 13, 2025 · 0753f66 · 0753f66
1 parent d53d454
commit 0753f66
Showing 1 changed file with 103 additions and 5 deletions.
diff --git a/docs/_docs/tools/control-script.adoc b/docs/_docs/tools/control-script.adoc
@@ -36,17 +36,16 @@ control.bat <connection parameters> <command> <arguments>
 
 == Connecting to Cluster
 
-When executed without connection parameters, the control script tries to connect to a node running on localhost (`localhost:11211`).
+NOTE: Starting from Apache Ignite version 2.17, the utility by default uses a connection through the thin client protocol (configured on a node via `org.apache.ignite.configuration.ClientConnectorConfiguration`). See link:#migration-to-the-thin-client-protocol[Migration Notes] for more information.
+
+When executed without connection parameters, the control script tries to connect to a node running on localhost (`localhost:10800`).
 If you want to connect to a node that is running on a remove machine, specify the connection parameters.
 
 [cols="2,3,1",opts="header"]
 |===
 |Parameter | Description | Default Value
-
 | --host HOST_OR_IP | The host name or IP address of the node. | `localhost`
-
-| --port PORT | The port to connect to. | `11211`
-
+| --port PORT | The port to connect to. | `10800`
 | --user USER | The user name. |
 | --password PASSWORD |The user password. |
 | --ping-interval PING_INTERVAL | The ping interval. | 5000
@@ -63,6 +62,105 @@ If you want to connect to a node that is running on a remove machine, specify th
 | --ssl-factory SSL_FACTORY_PATH | Custom SSL factory Spring xml file path. |
 |===
 
+== Migration to the thin client protocol
+
+With the default configuration of Ignite, no migration actions will be required. Additional configuration of the connector is no longer necessary.
+
+If you connect to the wrong connector, you will receive an error and may see the message:
+
+`Make sure you are connecting to the client connector (configured on a node via 'org.apache.ignite.configuration.ClientConnectorConfiguration'). Connection to the REST connector was deprecated and will be removed for the control utility in future releases. Set up the 'IGNITE_CONTROL_UTILITY_USE_CONNECTOR_CONNECTION' system property to 'true' to forcefully connect to the REST connector (configured on a node via 'org.apache.ignite.configuration.ConnectorConfiguration').`
+
+To ensure backward compatibility, a system property has been added to provide the old behavior (note: it will be removed in version 2.18):
+
+[tabs]
+--
+tab:Unix[]
+[source, shell]
+----
+export IGNITE_CONTROL_UTILITY_USE_CONNECTOR_CONNECTION=true;
+control.sh --state --host x.x.x.x --port 11212
+----
+tab:Windows[]
+[source, shell]
+----
+SET IGNITE_CONTROL_UTILITY_USE_CONNECTOR_CONNECTION=true
+control.bat --state --host x.x.x.x --port 11212
+----
+--
+
+In some cases, the following actions may be required to migrate user scripts using the utility:
+
+=== 1. A custom port is specified:
+
+[tabs]
+--
+tab:Unix[]
+[source, shell]
+----
+control.sh --state --host x.x.x.x --port 11212
+----
+tab:Windows[]
+[source, shell]
+----
+control.bat --state --host x.x.x.x --port 11212
+----
+--
+
+To migrate, specify the port for the thin client connector:
+
+[tabs]
+--
+tab:Unix[]
+[source, shell]
+----
+control.sh --state --host x.x.x.x
+control.sh --state --host x.x.x.x --port 10801
+----
+tab:Windows[]
+[source, shell]
+----
+control.bat --state --host x.x.x.x
+control.bat --state --host x.x.x.x --port 10801
+----
+--
+
+=== 2. A custom SSL factory for the binary REST connector is specified, different from the SSL factory for the thin client connector:
+
+[tabs]
+--
+tab:Unix[]
+[source, shell]
+----
+control.sh --state --ssl-factory connector-ssl-factory.xml
+----
+tab:Windows[]
+[source, shell]
+----
+control.bat --state --ssl-factory connector-ssl-factory.xml
+----
+--
+
+To migrate, specify the SSL factory for the thin client connector:
+
+[tabs]
+--
+tab:Unix[]
+[source, shell]
+----
+control.sh --state --ssl-factory ignite-ssl-factory.xml
+control.sh --state --ssl-factory client-connector-ssl-factory.xml
+----
+tab:Windows[]
+[source, shell]
+----
+control.bat --state --ssl-factory ignite-ssl-factory.xml
+control.bat --state --ssl-factory client-connector-ssl-factory.xml
+----
+--
+
+=== 3. The client connector is disabled.
+
+Enable it in the configuration (`IgniteConfiguration#setClientConnectorConfiguration`).
 
 == Activation, Deactivation and Topology Management