HoustonPutman commented on a change in pull request #193: URL: https://github.com/apache/lucene-solr-operator/pull/193#discussion_r566324592
########## File path: docs/solr-cloud/solr-cloud-crd.md ########## @@ -127,4 +127,118 @@ the solr-operator can manage Zookeeper ensemble(s) for you. Using the [zookeeper-operator](https://github.com/pravega/zookeeper-operator), a new Zookeeper ensemble can be spun up for each solrCloud that has this option specified. -The startup parameter `zookeeper-operator` must be provided on startup of the solr-operator for this parameter to be available. \ No newline at end of file +The startup parameter `zookeeper-operator` must be provided on startup of the solr-operator for this parameter to be available. + +## Override Built-in Solr Configuration Files + +The Solr operator deploys well-configured SolrCloud instances with minimal input required from human operators. +As such, the operator installs various configuration files automatically, including `solr.xml` for node-level settings and `log4j2.xml` for logging. +However, there may come a time when you need to override the built-in configuration files with custom settings. + +In general, users can provide custom config files by providing a ConfigMap in the same namespace as the SolrCloud instance; +all custom config files should be stored in the same user-provided ConfigMap under different keys. +Point your SolrCloud definition to a user-provided ConfigMap using the following structure: +``` +spec: + ... + customSolrKubeOptions: + configMapOptions: + providedConfigMap: <Custom-ConfigMap-Here> +``` + +### Custom solr.xml + +Solr pods load node-level configuration settings from `/var/solr/data/solr.xml`. +This important configuration file gets created by the `cp-solr-xml` initContainer which bootstraps the `solr.home` directory on each pod before starting the main container. +The default `solr.xml` is mounted into the `cp-solr-xml` initContainer from a ConfigMap named `<INSTANCE>-solrcloud-configmap` (where `<INSTANCE>` is the name of your SolrCloud instance) created by the Solr operator. + +_Note: The data in the default ConfigMap is not editable! Any changes to the `solr.xml` in the default ConfigMap created by the operator will be overwritten during the next reconcile cycle._ + +Many of the specific values in `solr.xml` can be set using Java system properties; for instance, the following setting controls the read timeout for the HTTP client used by Solr's `HttpShardHandlerFactory`: +``` +<int name="socketTimeout">${socketTimeout:600000}</int> +``` +The `${socketTimeout:600000}` syntax means pull the value from a Java system property named `socketTimeout` with default `600000` if not set. + +You can set Java system properties using the `solrOpts` string in your SolrCloud definition, such as: +``` +spec: + solrOpts: -DsocketTimeout=300000 +``` +This same approach works for a number of settings in `solrconfig.xml` as well. + +However, if you need to customize `solr.xml` beyond what can be accomplished with Java system properties, +then you need to supply your own `solr.xml` in a ConfigMap in the same namespace where you deploy your SolrCloud instance. +Provide your custom XML in the ConfigMap using `solr.xml` as the key as shown in the example below: +``` +--- +kind: ConfigMap +apiVersion: v1 +metadata: + name: custom-solr-xml +data: + solr.xml: | + <?xml version="1.0" encoding="UTF-8" ?> + <solr> + ... CUSTOM CONFIG HERE ... + </solr> +``` + +You can get the default `solr.xml` from a Solr pod as a starting point for creating a custom config using `kubectl cp` as shown in the example below: +``` +SOLR_POD_ID=$(kubectl get pod -l technology=solr-cloud --no-headers -o custom-columns=":metadata.name" | head -1) +kubectl cp $SOLR_POD_ID:/var/solr/data/solr.xml ./custom-solr.xml +``` +This copies the default config from the first Solr pod found in the namespace and names it `custom-solr.xml`. Customize the settings in `custom-solr.xml` as needed and then create a ConfigMap using YAML. + +_Note: Using `kubectl create configmap --from-file` scrambles the XML formatting, so we recommend defining the configmap YAML as shown above to keep the XML formatted properly._ + +Point your SolrCloud instance at the custom ConfigMap using: +``` + customSolrKubeOptions: + configMapOptions: + providedConfigMap: custom-solr-xml +``` + +#### Changes to Custom Config Trigger Rolling Restarts + +The Solr operator stores the MD5 hash of your custom XML in the StatefulSet's pod spec annotations (`spec.template.metadata.annotations`). To see the current annotations for your Solr pods, you can do: +``` +kubectl annotate pod -l technology=solr-cloud --list=true +``` +If the custom `solr.xml` changes in the user-provided ConfigMap, then the operator triggers a rolling restart of Solr pods to apply the updated configuration settings automatically. + +To summarize, if you need to customize `solr.xml`, provide your own version in a ConfigMap and changes made to the XML in the ConfigMap are automatically applied to your Solr pods. + +### Custom Log Configuration + +As with `solr.xml`, the operator configures Solr with a default Log4j2 configuration file: `-Dlog4j.configurationFile=/var/solr/log4j2.xml`. Review comment: Unlike with `solr.xml`, the operator uses the default log4j2 configuration file that ships with Solr. ########## File path: docs/solr-cloud/solr-cloud-crd.md ########## @@ -127,4 +127,118 @@ the solr-operator can manage Zookeeper ensemble(s) for you. Using the [zookeeper-operator](https://github.com/pravega/zookeeper-operator), a new Zookeeper ensemble can be spun up for each solrCloud that has this option specified. -The startup parameter `zookeeper-operator` must be provided on startup of the solr-operator for this parameter to be available. \ No newline at end of file +The startup parameter `zookeeper-operator` must be provided on startup of the solr-operator for this parameter to be available. + +## Override Built-in Solr Configuration Files + +The Solr operator deploys well-configured SolrCloud instances with minimal input required from human operators. +As such, the operator installs various configuration files automatically, including `solr.xml` for node-level settings and `log4j2.xml` for logging. +However, there may come a time when you need to override the built-in configuration files with custom settings. + +In general, users can provide custom config files by providing a ConfigMap in the same namespace as the SolrCloud instance; +all custom config files should be stored in the same user-provided ConfigMap under different keys. +Point your SolrCloud definition to a user-provided ConfigMap using the following structure: +``` +spec: + ... + customSolrKubeOptions: + configMapOptions: + providedConfigMap: <Custom-ConfigMap-Here> +``` + +### Custom solr.xml + +Solr pods load node-level configuration settings from `/var/solr/data/solr.xml`. +This important configuration file gets created by the `cp-solr-xml` initContainer which bootstraps the `solr.home` directory on each pod before starting the main container. +The default `solr.xml` is mounted into the `cp-solr-xml` initContainer from a ConfigMap named `<INSTANCE>-solrcloud-configmap` (where `<INSTANCE>` is the name of your SolrCloud instance) created by the Solr operator. + +_Note: The data in the default ConfigMap is not editable! Any changes to the `solr.xml` in the default ConfigMap created by the operator will be overwritten during the next reconcile cycle._ + +Many of the specific values in `solr.xml` can be set using Java system properties; for instance, the following setting controls the read timeout for the HTTP client used by Solr's `HttpShardHandlerFactory`: +``` +<int name="socketTimeout">${socketTimeout:600000}</int> +``` +The `${socketTimeout:600000}` syntax means pull the value from a Java system property named `socketTimeout` with default `600000` if not set. + +You can set Java system properties using the `solrOpts` string in your SolrCloud definition, such as: +``` +spec: + solrOpts: -DsocketTimeout=300000 +``` +This same approach works for a number of settings in `solrconfig.xml` as well. + +However, if you need to customize `solr.xml` beyond what can be accomplished with Java system properties, +then you need to supply your own `solr.xml` in a ConfigMap in the same namespace where you deploy your SolrCloud instance. +Provide your custom XML in the ConfigMap using `solr.xml` as the key as shown in the example below: +``` +--- +kind: ConfigMap +apiVersion: v1 +metadata: + name: custom-solr-xml +data: + solr.xml: | + <?xml version="1.0" encoding="UTF-8" ?> + <solr> + ... CUSTOM CONFIG HERE ... + </solr> +``` Review comment: I would put a bolded statement here stating the need for a `<hostPort>${hostPort}</hostPort>` under the <solr><solrcloud> section. ########## File path: docs/solr-cloud/solr-cloud-crd.md ########## @@ -127,4 +127,118 @@ the solr-operator can manage Zookeeper ensemble(s) for you. Using the [zookeeper-operator](https://github.com/pravega/zookeeper-operator), a new Zookeeper ensemble can be spun up for each solrCloud that has this option specified. -The startup parameter `zookeeper-operator` must be provided on startup of the solr-operator for this parameter to be available. \ No newline at end of file +The startup parameter `zookeeper-operator` must be provided on startup of the solr-operator for this parameter to be available. + +## Override Built-in Solr Configuration Files + +The Solr operator deploys well-configured SolrCloud instances with minimal input required from human operators. +As such, the operator installs various configuration files automatically, including `solr.xml` for node-level settings and `log4j2.xml` for logging. +However, there may come a time when you need to override the built-in configuration files with custom settings. + +In general, users can provide custom config files by providing a ConfigMap in the same namespace as the SolrCloud instance; +all custom config files should be stored in the same user-provided ConfigMap under different keys. +Point your SolrCloud definition to a user-provided ConfigMap using the following structure: +``` +spec: + ... + customSolrKubeOptions: + configMapOptions: + providedConfigMap: <Custom-ConfigMap-Here> +``` + +### Custom solr.xml + +Solr pods load node-level configuration settings from `/var/solr/data/solr.xml`. +This important configuration file gets created by the `cp-solr-xml` initContainer which bootstraps the `solr.home` directory on each pod before starting the main container. +The default `solr.xml` is mounted into the `cp-solr-xml` initContainer from a ConfigMap named `<INSTANCE>-solrcloud-configmap` (where `<INSTANCE>` is the name of your SolrCloud instance) created by the Solr operator. + +_Note: The data in the default ConfigMap is not editable! Any changes to the `solr.xml` in the default ConfigMap created by the operator will be overwritten during the next reconcile cycle._ + +Many of the specific values in `solr.xml` can be set using Java system properties; for instance, the following setting controls the read timeout for the HTTP client used by Solr's `HttpShardHandlerFactory`: +``` +<int name="socketTimeout">${socketTimeout:600000}</int> +``` +The `${socketTimeout:600000}` syntax means pull the value from a Java system property named `socketTimeout` with default `600000` if not set. + +You can set Java system properties using the `solrOpts` string in your SolrCloud definition, such as: +``` +spec: + solrOpts: -DsocketTimeout=300000 +``` +This same approach works for a number of settings in `solrconfig.xml` as well. + +However, if you need to customize `solr.xml` beyond what can be accomplished with Java system properties, +then you need to supply your own `solr.xml` in a ConfigMap in the same namespace where you deploy your SolrCloud instance. +Provide your custom XML in the ConfigMap using `solr.xml` as the key as shown in the example below: +``` +--- +kind: ConfigMap +apiVersion: v1 +metadata: + name: custom-solr-xml +data: + solr.xml: | + <?xml version="1.0" encoding="UTF-8" ?> + <solr> + ... CUSTOM CONFIG HERE ... + </solr> +``` Review comment: Also say that your statefulset and solr pods will not be created if this is missing from the XML. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org For additional commands, e-mail: issues-h...@lucene.apache.org
