https://issues.redhat.com/browse/ACM-26272

search/custom_search_console.adoc → search/customize_console_search.adoc

@@ -1,7 +1,17 @@
-[#custom-search-console]
-== Customizing the search console
+[#customize-search-console]
+= Customizing the console for Search
 
-Customize your search results and limits. Complete the following tasks to perform the customization:
+Customize your console for Search to specify how you want data and search results to be displayed. 
+
+*Required access:* Cluster administrator 
+
+.Prerequisites
+
+- You must have access to the `open-cluster-management` namespace.
+
+.Procedure
+
+Complete the following tasks to perform the customization:
 
 . Customize the search result limit from the {ocp-short} console.
 .. Update the `console-mce-config` in the `multicluster-engine` namespace. These settings apply to all users and might affect performance. View the following performance parameter descriptions:
@@ -10,15 +20,16 @@ Customize your search results and limits. Complete the following tasks to perfor
 - `SEARCH_RESULT_LIMIT` - The maximum amount of search results displayed in the console. Default value is `1000`. To remove this limit set to `-1`.
 - `SEARCH_AUTOCOMPLETE_LIMIT` - The maximum number of suggestions retrieved for the search bar typeahead. Default value is `10,000`. To remove this limit set to `-1`.
 
-.. Run the following `patch` command from the {ocp-short} console to change the search result to 100 items:
+.. Change the search result to `100` items by running the following `patch` command from the {ocp-short} console:
 
 +
 [source,bash]
 ----
 oc patch configmap console-mce-config -n multicluster-engine --type merge -p '{"data":{"SEARCH_RESULT_LIMIT":"100"}}'
 ----
 
-. To add, edit, or remove suggested searches, create a config map named `console-search-config` and configure the `suggestedSearches` section. Suggested searches that are listed are also displayed from the console. It is required to have an `id, name, and searchText` for each search object. View the following config map example:
+. To add, edit, or remove suggested searches, create a config map named `console-search-config` and configure the `suggestedSearches` section. Suggested searches that are listed are also displayed from the console. It is required to have an `id, name, and searchText` for each search object.
+.. Add the namespace where search is enabled. View the following config map example:
 
 +
 [source,yaml]
@@ -27,7 +38,7 @@ kind: ConfigMap
 apiVersion: v1
 metadata:
   name: console-search-config
-  namespace: <acm-namespace> <1>
+  namespace: <acm-namespace>
 data:
   suggestedSearches: |-
     [
@@ -56,6 +67,4 @@ data:
         "searchText": "kind:VirtualMachine"
       }
     ] 
-----
-+
-<1> Add the namespace where search is enabled.
+----

search/customize_search_service.adoc

@@ -0,0 +1,129 @@
+[#customize-search-service]
+= Customizing the Search service
+
+Customize the Search service to set up persistent storage, to fine-tune for performance and scalability, or to modify certain behaviors through environment variables. Access the search configuration options from the search operator which watches the `search-v2-operator` custom resource, reconciles the changes, and updates active pods.
+
+*Required access:* Cluster administrator
+
+.Prerequisites
+
+- You must have access to the `open-cluster-management` namespace.
+
+.Procedure
+
+Complete the following steps to customize the Search service:
+
+. Modify the default values in the `search-v2-operator` custom resource.
+.. To view details of the custom resource, run the following command:
+
++
+[source,bash]
+----
+oc get search search-v2-operator -n <acm-namespace> -o yaml
+----
+
+.. Configure a persistent volume claim for your clusters that are in production. If the empty directory size is limited for your PostgreSQL database, save your PostgreSQL data on a persistent volume claim to improve search performance.
+
++
+*Notes:*
+
+- When you install {acm-short}, the PostgreSQL database is configured to save the PostgreSQL data in an empty directory (`emptyDir`) volume.
+- When a persistent volume claim is not configured, the `SearchPVCNotPresent` alert is displayed in the Status pane.
+
+.. To persist your search data, select a storage class from your {acm-short} hub cluster.
+.. For example, create a persistent volume claim if you select the `gp2` storageclass and mount the claim to the `search-postgres` pod. Your configuration might resemble the following example:
+
++
+[source,yaml]
+----
+apiVersion: search.open-cluster-management.io/v1alpha1
+kind: Search
+metadata:
+  name: search-v2-operator
+  namespace: open-cluster-management
+  labels:
+    cluster.open-cluster-management.io/backup: ""
+spec:
+  dbStorage:
+    size: 10Gi
+    storageClassName: gp2
+----
+
+.. Modify the storage size if you need to. By default, the storage size is `10Gi`. For example, `20Gi` might be sufficient for about 200 managed clusters.
+
+. Optimize cost by tuning the pod memory or CPU requirements, replica count, and update log levels for any of the four search pods: `indexer`, `database`, `queryapi`, or `collector`.
+
+.. Update the `deployment` section of the `search-v2-operator` custom resource. There are four deployments managed by the `search-v2-operator`, which can be updated individually.
+.. Apply resources for the `indexer`, `database`, `queryapi`, or `collector` pod.
+.. Add multiple environment variables in the `envVar` section to specify a value for each variable that you name.
+.. Specify a value for each variable that you name by adding multiple environment variables in the `envVar` specification.
+.. Add the `- -v=3` argument for the `queryapi` specification to control the log level verbosity for any of the four pods.
+Your `search-v2-operator` custom resource might resemble the following file:
+
++
+[source,yaml]
+----
+apiVersion: search.open-cluster-management.io/v1alpha1
+kind: Search
+metadata:
+  name: search-v2-operator
+  namespace: open-cluster-management
+spec:
+  deployments:
+    collector:
+      resources:
+        limits:
+          cpu: 500m
+          memory: 128Mi
+        requests:
+          cpu: 250m
+          memory: 64Mi
+    indexer:
+      replicaCount: 3
+    database:
+        envVar:
+          - name: POSTGRESQL_EFFECTIVE_CACHE_SIZE
+            value: 1024MB
+          - name: POSTGRESQL_SHARED_BUFFERS
+            value: 512MB
+          - name: WORK_MEM
+            value: 128MB
+    queryapi:
+      arguments:
+      - -v=3
+----
+
+. Apply memory resources for the `indexer` pod. See the following example:
+
++
+[source,yaml]
+----
+    indexer:
+      resources:
+        limits:
+          memory: 5Gi
+        requests:
+          memory: 1Gi 
+----
+
+. Define the node placement for search pods.
+.. Update the `Placement` resource of search pods by using the `nodeSelector` parameter, or the `tolerations` parameter. View the following example configuration:
+
++
+[source,yaml]
+----
+spec:
+ dbStorage:
+  size: 10Gi
+ deployments:
+  collector: {}
+  database: {}
+  indexer: {}
+  queryapi: {}
+ nodeSelector:
+  node-role.kubernetes.io/infra: ""
+ tolerations:
+ - effect: NoSchedule
+  key: node-role.kubernetes.io/infra
+  operator: Exists
+----

search/main.adoc

@@ -5,6 +5,7 @@ include::modules/common-attributes.adoc[]
 include::search_intro.adoc[leveloffset=+1]
 include::search_console.adoc[leveloffset=+2]
 include::create_search_collection.adoc[leveloffset=+2]
-include::custom_search_console.adoc[leveloffset=+2]
+include::customize_search_service.adoc[leveloffset=+2]
+include::customize_console_search.adoc[leveloffset=+2]
 include::query_search_console.adoc[leveloffset=+2]
 include::search_klusterlet_addon.adoc[leveloffset=+2]

search/query_search_console.adoc

@@ -3,33 +3,44 @@
 
 You can type any text value in the _Search box_ and results include anything with that value from any property, such as a name or namespace. Queries that contain an empty space are not supported.
 
+As you search for resources, you receive other resources that are related to your original search result, which help you visualize how the resources interact with other resources in the system.
+
 *Required access:* Cluster administrator
 
 For more specific search results, include the property selector in your search. You can combine related values for the property for a more precise scope of your search. For example, search for `cluster:dev red` to receive results that match the string "red" in the `dev` cluster. 
 
+.Procedure
+
+Search returns and lists each cluster with the resource that you search. For resources in the _hub_ cluster, the cluster name is displayed as _local-cluster_.
+
+You can change the `local-cluster` name if the `enabled` field is set to `false`. You must use 34 or fewer characters for the `<your-local-cluster-name>` value. The `local-cluster` cannot be renamed if it is set as `enabled: true`.
+
+*Note:* If you change the default name of your `local-cluster` to another value, the results appear within the changed local cluster name.
+
+Your search results are grouped by `kind`, and each resource `kind` is grouped in a table. Search options depend on your cluster objects. Refine your results with specific labels.
+
 Complete the following steps to make queries with search:
 
 . Click *Search* in the navigation menu.
 . Type a word in the _Search box_, then Search finds your resources that contain that value.
-- As you search for resources, you receive other resources that are related to your original search result, which help you visualize how the resources interact with other resources in the system.
-- Search returns and lists each cluster with the resource that you search.
-For resources in the _hub_ cluster, the cluster name is displayed as _local-cluster_.
-- Your search results are grouped by `kind`, and each resource `kind` is grouped in a table.
-- Your search options depend on your cluster objects.
-- You can refine your results with specific labels.
-Search is case-sensitive when you query labels.
-See the following examples that you can select for filtering: `name`, `namespace`, `status`, and other resource fields. Auto-complete provides suggestions to refine your search. See the following example:
+
++
+*Note:* Search is case-sensitive when you query labels.
+
+. See the following examples that you can select for filtering: `name`, `namespace`, `status`, and other resource fields. Auto-complete provides suggestions to refine your search. See the following example:
 +
 - Search for a single field, such as `kind:pod` to find all pod resources.
 - Search for multiple fields, such as `kind:pod namespace:default` to find the pods in the default namespace.
 +
 *Notes:*
 +
-** When you search for more than one property selector with multiple values, the search returns either of the values that were queried. View the following examples:
-** When you search for `kind:Pod name:a`, any pod named `a` is returned.
-** When you search for `kind:Pod name:a,b`, any pod named `a` or `b` are returned.
-** Search for `kind:pod status:!Running` to find all pod resources where the status is not `Running`.
-** Search for `kind:pod restarts:>1` to find all pods that restarted at least twice.
+- When you search for more than one property selector with multiple values, the search returns either of the values that were queried. View the following examples:
+- When you search for `kind:Pod name:a`, any pod named `a` is returned.
+- When you search for `kind:Pod name:a,b`, any pod named `a` or `b` are returned.
+- Search for `kind:pod status:!Running` to find all pod resources where the status is not `Running`.
+- Search for `kind:pod restarts:>1` to find all pods that restarted at least twice.
+
+. Specify your search query by selecting the *Advanced search* drop-down button to filter the _Column_, _Operator_, and _Value_ options or add a search constraint.
 . If you want to save your search, click the *Save search* icon.
 . To download your search results, select the *Export as CSV* button.