https://issues.redhat.com/browse/ACM-26272 #8448
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: dockerymick The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
swopebe
changed the title
search/custom_search_console.adoc
Outdated
| == Customizing the search console | ||
|
|
||
| Customize your search results and limits. Complete the following tasks to perform the customization: | ||
| Customize your search results and limits to improve search results. The search operator watches the `search-v2-operator` custom resource, reconciles the changes and updates active pods. |
There was a problem hiding this comment.
This statement is correct, but I'd move it below around line 72.
Maybe we should divide this document in 2 parts.
-
Customizing the search console.
This section explains how to customize the search console (web UI). This includes things like how data is presented and how many results. -
Customizing the search service (or search back-end)
This section is about customizing the search back-end components. Users might need to customize this to setup persistent storage, fine-tune for performance and scalability, or modify certain behaviors through environment variables. These configuration options are in thesearch-v2-oepratorresource.
search/custom_search_console.adoc
Outdated
| oc get search search-v2-operator -o yaml | ||
| ---- | ||
|
|
||
| .. If the empty directory size is limited for your PostgreSQL database, save your PostgreSQL data on a persistent volume claim to improve search performance. |
There was a problem hiding this comment.
We are changing the guidance to say that customers must configure a persistent volume for clusters in production.
Maybe this can be addressed in a different PR. Here's the jira task: https://issues.redhat.com/browse/ACM-25259
Co-authored-by: Jorge Padilla <[email protected]>
search/custom_search_console.adoc
Outdated
| Customize your search results and limits. Complete the following tasks to perform the customization: | ||
| Customize your search console to specify how you want data and search results to be displayed. | ||
|
|
||
| *Required access:* Cluster administrator |
There was a problem hiding this comment.
Do we have a RHACM administrator access role? To make these changes user doesn't need full cluster admin. They only need to be admin on the ACM namespaces multicluster-engine and open-cluster-management
There was a problem hiding this comment.
We can specify that, thanks! I am not sure we should mention mce in this file. We do have mce-acm integrations docs tho. Let me get some clarity from Brandi
There was a problem hiding this comment.
I have not see an ACM admin role, no we normally just writing Cluster administrator. @dockerymick
search/custom_search_console.adoc
Outdated
|
|
||
| .Prerequisites | ||
|
|
||
| - Are there any prereqs? |
There was a problem hiding this comment.
No prereqs, just ACM installed.
search/custom_search_console.adoc
Outdated
| + | ||
| <1> Add the namespace where search is enabled. | ||
|
|
||
| . 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. |
There was a problem hiding this comment.
Maybe this line is out of context here?
search/custom_search_service.adoc
Outdated
| [#customize-search-service] | ||
| = Customizing the Search service | ||
|
|
||
| Customize the Search service to improve search results. Set up persistent storage, fine-tune for performance and scalability, or 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. |
There was a problem hiding this comment.
Customize the Search service to improve search results.
This statement is a little misleading because search results won't change. Typically users will need configure search to fine-tune to their specific environments or scale needs. The next sentence includes some specific reasons.
search/custom_search_service.adoc
Outdated
| *Notes:* | ||
|
|
||
| - When you install {acm-short}, the PostgreSQL database is configured to save the PostgreSQL data in an empty directory (`emptyDir`) volume. | ||
| - To receive information-only alerts about search storage, consider setting up the persistent volume claim for search. |
There was a problem hiding this comment.
The alert is generated by us to remind users when the PVC is not configured.
Here's more context about the alert, see the Status section "SearchPVCNotPresent"
There was a problem hiding this comment.
The image isn't displaying
search/custom_search_service.adoc
Outdated
| - When you install {acm-short}, the PostgreSQL database is configured to save the PostgreSQL data in an empty directory (`emptyDir`) volume. | ||
| - To receive information-only alerts about search storage, consider setting up the persistent volume claim for search. | ||
| .. To back up your search data, select a storage class from your {acm-short} hub cluster. |
There was a problem hiding this comment.
| .. To back up your search data, select a storage class from your {acm-short} hub cluster. | |
| .. To persist the search data, select a storage class from your {acm-short} hub cluster. |
There's no backup. The difference is where the data is stored memory vs. persistent volume. The benefit is that memory is volatile and a persistent volume is well "persistent".
search/search_intro.adoc
Outdated
| * xref:../search/custom_search_service.adoc#custom-search-console[Customizing the Search service] | ||
| * xref:../search/custom_search_console.adoc#custom-search-console[Customizing the search console] |
There was a problem hiding this comment.
Capitalization inconsistency Search vs. search.
There was a problem hiding this comment.
I used a capital "s" when referring to the service because we capitalize the names of a feature. If we are simply writing the word "search" as a verb, I use a lowercase "s". Maybe we can say "Customizing the console for Search", since there is not an independent search console.
There was a problem hiding this comment.
Got it, it just looks odd when looking at both lines together.
I like "Customizing the console for Search", and as you point out it's also more accurate.
| .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_. |
There was a problem hiding this comment.
Not always true. There was a new feature in 2.13/2.14(?) that allows users to rename local-cluster to their custom name.
There was a problem hiding this comment.
I see this note used in our doc, "Note: If you change the default name of your local-cluster to another value, the results appear within the changed local cluster name."
There was a problem hiding this comment.
It was part of a large effort to allow the user to change their name of the local cluster. We discussed this quite a bit in a couple meetings.
This is discussed in adv install:
For resources in the hub cluster, the cluster name is displayed as local-cluster.[#local-cluster]
== Local-cluster enablement
By default, the cluster that is running {mce-short} is the local cluster, which is a hub cluster that manages itself and is designated as the local-cluster in the list of clusters.
In the MultiClusterEngine resource, the local cluster name is set from the spec.localClusterName value. The enabled setting specifies whether the feature is enabled or disabled.
The enabled: true setting designates your cluster as a local-cluster, and the enabled: false setting does not. See the following sample where the local-cluster is enabled with the enabled: true value.
[source,yaml]
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.
To install {mce-short} without designating it as a local-cluster, change the spec.overrides.components settings to enabled: false. See the following YAML sample:
I think we need to say that it can be changed, but then document any consequences as a result. I think it should be more than a note.
search/customize_search_service.adoc
Outdated
| [#customize-search-service] | ||
| = Customizing the Search service | ||
|
|
||
| Customize the Search service set up persistent storage, fine-tune for performance and scalability, or 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. |
There was a problem hiding this comment.
Reading this description out loud, it is a bit confusing.
There is one missing comma before which, but more is needed to make the first line agree or be clearer.
search/customize_console_search.adoc
Outdated
| 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 in the `open-cluster-management` namespace |
There was a problem hiding this comment.
we don't normally write this. In the prereqs, you would put that you need access to the namespace. This line should look similar across the doc, so you can check to see how it is written elsewhere, but we usually just put the role here.
There was a problem hiding this comment.
Thanks ! I was thinking about how I specified roles for the fine-grain topic. Even then, the fine-grain doc is consistent with not having the namespace in the required access portion. Great callout!
search/customize_search_service.adoc
Outdated
| [#customize-search-service] | ||
| = Customizing the Search service | ||
|
|
||
| Customize the Search service to set up persistent storage, fine-tune for performance and scalability, or 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. |
There was a problem hiding this comment.
fine-tune here is odd, in that it is written in a way to be taken as a noun.
do you mean to "fine-tune performance and scalability" or create a "fine-tune"?
There was a problem hiding this comment.
Fine-tune is the verb. What do you think about us saying "adjust settings for performance and scalability..."
| - effect: NoSchedule | ||
| key: node-role.kubernetes.io/infra | ||
| operator: Exists | ||
| ---- |
There was a problem hiding this comment.
the rest of the content looks really good.
search/search_console.adoc
Outdated
| == Additional resources | ||
|
|
||
| - For more topics about the {acm} console, see link:../console/console_intro.adoc#web-console[Web console]. | ||
| - 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. |
There was a problem hiding this comment.
| - 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. | |
| - 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. |
|
The updated note on the SearchPVCNotPresent alert looks good to me 👍 |
Co-authored-by: swope <[email protected]>
| 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_. | ||
|
|
||
| *Note:* If you change the default name of your _local-cluster_ to another value, the results appear within the changed local cluster name. |
There was a problem hiding this comment.
| 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_. | |
| *Note:* If you change the default name of your _local-cluster_ to another value, the results appear within the changed local cluster name. | |
| 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. |
There was a problem hiding this comment.
@jlpadilla are there any other consequences that need to be mentioned ?
There was a problem hiding this comment.
No other consequences, we just change the cluster name from "local-cluster" to the configured name.
4 participants
No description provided.