diff --git a/search/custom_search_console.adoc b/search/customize_console_search.adoc similarity index 78% rename from search/custom_search_console.adoc rename to search/customize_console_search.adoc index 7be2a84fb2..599fba56d5 100644 --- a/search/custom_search_console.adoc +++ b/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,7 +20,7 @@ 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] @@ -18,7 +28,8 @@ Customize your search results and limits. Complete the following tasks to perfor 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: <1> + namespace: data: suggestedSearches: |- [ @@ -56,6 +67,4 @@ data: "searchText": "kind:VirtualMachine" } ] ----- -+ -<1> Add the namespace where search is enabled. \ No newline at end of file +---- \ No newline at end of file diff --git a/search/customize_search_service.adoc b/search/customize_search_service.adoc new file mode 100644 index 0000000000..405e646a22 --- /dev/null +++ b/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 -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 +---- diff --git a/search/main.adoc b/search/main.adoc index 8d39de60fb..342bae9d6f 100644 --- a/search/main.adoc +++ b/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] \ No newline at end of file diff --git a/search/query_search_console.adoc b/search/query_search_console.adoc index 487589b7d5..4e5c8535e4 100644 --- a/search/query_search_console.adoc +++ b/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 `` 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. diff --git a/search/search_console.adoc b/search/search_console.adoc index 70ccefe0fd..cb09727aa5 100644 --- a/search/search_console.adoc +++ b/search/search_console.adoc @@ -3,11 +3,8 @@ For {acm}, search provides visibility into your Kubernetes resources across all of your clusters. Search also indexes the Kubernetes resources and the relationships to other resources. -* <> -* <> -* <> +Search is configured by default on the hub cluster. When you provision or manually import a managed cluster, the `klusterlet-addon-search` is enabled. -[#search-components] == Search components The search architecture is composed of the following components: @@ -63,120 +60,6 @@ Provides access to all cluster data in the `search-indexer` through GraphQL and | Stores collected data from all managed clusters in an instance of the PostgreSQL database. |=== -Search is configured by default on the hub cluster. When you provision or manually import a managed cluster, the `klusterlet-addon-search` is enabled. If you want to disable search on your managed cluster, see link:../add-ons/modify_endpoint.adoc#modify-klusterlet-add-ons[Modifying the klusterlet add-ons settings of your cluster] for more information. - -[#search-customization] -== Search customization and configurations - -You can 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 -o yaml ----- - -The search operator watches the `search-v2-operator` custom resource, reconciles the changes and updates active pods. View the following descriptions of the configurations: - -- PostgreSQL database storage: -+ -When you install {acm-short}, the PostgreSQL database is configured to save the PostgreSQL data in an empty directory (`emptyDir`) volume. If the empty directory size is limited, you can save the PostgreSQL data on a Persistent Volume Claim (PVC) to improve search performance. You can select a storageclass from your {acm-short} hub cluster to back up your search data. For example, if you select the `gp2` storageclass 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 ----- -+ -This configuration creates a PVC named `gp2-search` and is mounted to the `search-postgres` pod. By default, the storage size is `10Gi`. You can modify the storage size. 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` pod). 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. 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: <1> - limits: - cpu: 500m - memory: 128Mi - requests: - cpu: 250m - memory: 64Mi - indexer: - replicaCount: 3 - database: <2> - envVar: - - name: POSTGRESQL_EFFECTIVE_CACHE_SIZE - value: 1024MB - - name: POSTGRESQL_SHARED_BUFFERS - value: 512MB - - name: WORK_MEM - value: 128MB - queryapi: - arguments: <3> - - -v=3 ----- -+ -<1> You can apply resources to an `indexer`, `database`, `queryapi`, or `collector` pod. -<2> You can add multiple environment variables in the `envVar` section to specify a value for each variable that you name. -<3> You can control the log level verbosity for any of the previous four pods by adding the `- -v=3` argument. -+ -See the following example where memory resources are applied to the indexer pod: -+ -[source,yaml] ----- - indexer: - resources: - limits: - memory: 5Gi - requests: - memory: 1Gi ----- - -- You can define the node placement for search pods. -+ -You can 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 ----- - -- 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. - -[#search-operations] == Search operations and data types Specify your search query by using search operations as conditions. Characters such as `+>, >=, <, <=, !=+` are supported. See the following search operation table: @@ -206,7 +89,8 @@ Specify your search query by using search operations as conditions. Characters s | Partial string match. |=== -[#additional-resources-search] + == Additional resources - For more topics about the {acm} console, see link:../console/console_intro.adoc#web-console[Web console]. +- If you want to disable the Search service on your managed cluster, see link:../add-ons/modify_endpoint.adoc#modify-klusterlet-add-ons[Modifying the klusterlet add-ons settings of your cluster] for more information. diff --git a/search/search_intro.adoc b/search/search_intro.adoc index 115c4673ea..8d3d4f61f6 100644 --- a/search/search_intro.adoc +++ b/search/search_intro.adoc @@ -5,6 +5,7 @@ Learn about the {acm-short} Search service. Use Search to query resource data fr * xref:../search/search_console.adoc#search-service[Search service] * xref:../search/create_search_collection.adoc#create-search-collection[Creating search configurable collection] -* xref:../search/custom_search_console.adoc#custom-search-console[Customizing search] +* xref:../search/customize_search_service.adoc#custom-search-console[Customizing the Search service] +* xref:../search/customize_console_search.adoc#custom-search-console[Customizing the console for Search] * xref:../search/query_search_console.adoc#query-console[Querying in the console] * xref:../search/search_klusterlet_addons.adoc#update-klusterlet-search[Updating klusterlet-addon-search deployments] \ No newline at end of file