[E&A] Add initial conceptual docs for CPS #4780
Conversation
Vale Linting ResultsSummary: 1 warning, 2 suggestions found
|
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/cross-project-search.md | 91 | Elastic.DontUse | Don't use 'just'. |
💡 Suggestions (2)
| File | Line | Rule | Message |
|---|---|---|---|
| explore-analyze/cross-project-search.md | 76 | Elastic.Wordiness | Consider using 'also' instead of 'In addition'. |
| explore-analyze/cross-project-search.md | 93 | Elastic.Wordiness | Consider using 'all' instead of 'all of '. |
The Vale linter checks documentation changes against the Elastic Docs style guide.
To use Vale locally or report issues, refer to Elastic style guide for Vale.
… into szabosteve/cps-init
| ## Project linking | ||
|
|
||
| In {{cps-init}}, projects have one of two roles: origin projects and linked projects. | ||
| An **origin project** is a project that you link other projects to. | ||
| A **linked project** is a project that is connected to an origin project. | ||
| After linking projects, you can run queries from the origin project that also search the linked projects ({{cps}}). | ||
| Project linking is not bidirectional. When you search from an origin project, the query runs against its linked projects as well. | ||
| However, searches initiated from a linked project do not run against the origin project. | ||
|
|
||
| You can link projects by using the Cloud UI. | ||
|
|
||
| <!-- | ||
| TODO: screenshot | ||
| --> | ||
|
|
||
| 1. On the home screen, select the project you want to use as the origin project and click **Manage**. | ||
| 2. Click **Configure** on the **{{cps-cap}}** tile. Or click **{{cps-cap}}** in the left-hand navigation. | ||
| 3. Click **Link projects**. | ||
| 4. Select the project you want to link from the project list. | ||
|
|
||
| <!-- | ||
| TODO: screenshot | ||
| --> | ||
|
|
||
| 5. Click **Review and save**. | ||
| 6. Review the selected projects. If you are satisfied, click **Save**. You can also view and copy the corresponding API request by clicking **View API request**. | ||
|
|
||
| <!-- | ||
| TODO: screenshot | ||
| --> |
There was a problem hiding this comment.
long term we probably want to move this out
cc: @marciw
quux00
left a comment
quux00
left a comment
There was a problem hiding this comment.
A good starting doc. First round review completed with several suggested changes or considerations. Once the first round is done I'll review again, especially with an eye towards what is missing from this doc and we can discuss where those go.
🔍 Preview links for changed docs |
szabosteve
added
documentation
quux00
left a comment
quux00
left a comment
There was a problem hiding this comment.
Looking really good. Second round review feedback.
| Refer to [the examples section](#cps-examples) for more. | ||
|
|
||
| <!-- | ||
| ### System and hidden indices |
There was a problem hiding this comment.
Do we intend to write up this section soon? I think it will be important. Or maybe it needs to have the security write-up done first to explain why system indices are treated differently from other indices?
There was a problem hiding this comment.
@quux00 My plan is to get this PR over the finishline and merge it. After that, I'll work on the "System and hidden indices", the "Security", and the "Examples" section, probably in separate PRs.
| ## Security | ||
|
|
||
| A high-level overview | ||
| --> |
There was a problem hiding this comment.
I propose that we also include a short section on not using skip_unavailable. We can put it at the bottom, since many users will not know enough about this to wonder, but experienced ES admins will likely be wondering where they set that value on linked projects. So I think we should discuss why skip_unavailable is not used in serverless and how error handling is instead handled.
There was a problem hiding this comment.
Here's a possible first draft of what I'm thinking of - feel to edit extensively:
One of the principles of cross-project search is that all projects should be treated the same in searches. Thus, searches on unqualified index expressions go to all projects by default, but it also means that error handling should be the same. This differs from cross-cluster search (used in ECH and on-prem deployments), where the remote cluster setting skip_unavailable (https://www.elastic.co/docs/explore-analyze/cross-cluster-search#skip-unavailable-clusters) is used to control whether certain types of errors from remote clusters should be ignored or cause the entire search to fail. This setting controls, for example, what to do if a remote cluster is offline when a search is initiated.
In serverless, the skip_unavailable setting is not used and it cannot be set on linked projects. Error handling during searches on the linked projects is controlled by the same settings as it is for origin-only searches:
ignore_unavailableandallow_no_indicescontrol error handling for missing resourcesallow_partial_search_results(in _search) andallow_partial_resultsin ES|QL control whether to return an error if only partial results can be obtained
For the case where a linked project is temporarily unavailable for a search or any project has shard failures during a search, the "allow partial" settings will control whether to return an error or return partial data. See the _search (add link) and ES|QL documentation (add link) for more detailed discussion of this setting.
THIS IS WIP
Page preview
Summary
Note
This page has the
hiddenattribute. It won't be indexed by search engines, nor appear in the navigation. It will be >accessible with a direct URL only while it's hidden.This PR contains the initial structure and draft content for the CPS conceptual documentation.
It covers:
The following will be covered in subsequent PRs:
Notes
The content outlined here may be extensive for a single page. We may consider splitting it into smaller subpages in a follow-up change.
TO DO
applies_totags based on the new guidelinesGenerative AI disclosure