[E&A] Add initial conceptual docs for CPS #4780
Conversation
Vale Linting ResultsSummary: 1 suggestion found 💡 Suggestions (1)
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.
| TODO: screenshot | ||
| --> | ||
|
|
||
| Your configuration is saved, a page with the list of linked projects opens. |
There was a problem hiding this comment.
nit: should this be: "When your configuration is saved, a .." or perhaps "Your configuration is saved and then a page with ..."
| ``` | ||
|
|
||
| For each linked project, the search runs only if an index named `logs` exists. | ||
| If a linked project does not have a `logs` index, that project is skipped and the search continues without returning an error. |
There was a problem hiding this comment.
No error is returned as long as at least one project has the index logs. Is that worth also stating here?
|
|
||
| ### Unqualified and qualified search expressions | ||
|
|
||
| {{cps-cap}} supports two types of search expressions: unqualified and qualified search expressions. The difference between them determines where a search request runs. |
|
|
||
| {{cps-cap}} supports two types of search expressions: unqualified and qualified search expressions. The difference between them determines where a search request runs. | ||
|
|
||
| An **unqualified** search expression does not include a project prefix or tags. When you use an unqualified expression, the search is performed according to the flat-world search model. |
There was a problem hiding this comment.
An unqualified search expression does not include a project prefix or tags
I think we should remove "or tags". If tags are present (such as in project routing), "logs" is still an unqualified expression. And you can only prefix with project alias, so my vote is to change this sentence to:
An unqualified search expression does not include a project alias prefix.
| An **unqualified** search expression does not include a project prefix or tags. When you use an unqualified expression, the search is performed according to the flat-world search model. | ||
| In this case, the search runs against the origin project and all its linked projects. | ||
|
|
||
| A **qualified** search expression includes additional qualifiers, such as project prefixes or tags, that explicitly control the scope of the search. |
There was a problem hiding this comment.
Same comment here. Qualified only refers to project alias prefixes. Searches with tags don't determine whether a resource is qualified or not.
| * `_region`: the CPS region | ||
| * `_type`: the project type (Observability, Search, Security) | ||
|
|
||
| Predefined tags are always start with an underscore `_`. |
There was a problem hiding this comment.
Let's also look at the Cloud UI. IIRC, on the cloud UI they don't necessarily show an underscore, but maybe when you edit the values, they do? Depends if you want to include Cloud UI info in this doc.
| The `project_routing` parameter is available on all cross-project-enabled endpoints. Refer to the [](#cps-supported-apis) for a full list of endpoints. | ||
| When you specify tags in the project_routing parameter, projects that do not match the specified tags are excluded from the search entirely. The query is never run on those projects. | ||
|
|
||
| For example, the following API request searches the `log` resource only on projects that have the `_alias:my_search_project` tag. |
| ``` | ||
|
|
||
| ::::{important} | ||
| Currently, project routing is only supported by the `_alias` tag. |
There was a problem hiding this comment.
Slight grammatical awkwardness here. Maybe this is better:
Currently, project routing is only supports using the
_aliastag.
|
|
||
| In both cases, the returned documents include the requested project metadata, which lets you identify which project each document originated from. | ||
|
|
||
| You can also use project tags in queries to filter or aggregate search results. |
There was a problem hiding this comment.
or sort
so "to filter, sort or aggregate" would be better here
| * [Field capabilities](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-field-caps) | ||
| * [Multi search](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-msearch) | ||
| * [Multi search template](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-msearch-template) | ||
| * [Painless execute API](elasticsearch://reference/scripting-languages/painless/painless-api-examples.md) |
There was a problem hiding this comment.
painless/execute is a weird beast. It's different enough from the other CPS-enabled endpoints that we may not want to include it in this list, but rather have a separate CPS description of it in its own page. You can sync with me to cover those details.
| ## 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. |
There was a problem hiding this comment.
I would try to reshape it a little bit. This definition feels very self-referential. Can we somehow emphasize that "origin" is is the current project for the user?
| 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}}). |
There was a problem hiding this comment.
#It feels like we wanna punch this up. It's not that you could, is that your searches that otherwise appeared local, would no longer be local.
In other words, the language in this section makes me think that I need to do something to run a query against linked projects. In reality it's the opposite, by default. This will happen, and I need to do something to prevent it.
|
|
||
| This section explains how search works in {{cps-init}}, including: | ||
|
|
||
| * how **flat-world search** operates across origin and linked projects |
There was a problem hiding this comment.
The introduce the concept of the flat world anywhere? We just sort of go ahead and start mentioning it.
Overall, it feels like we need to have some kind of a section at the start of this chapter that effectively describes the mental model of flat world in CPS. The current language makes me work really hard to infer the conceptss.
| ### Flat-world search | ||
|
|
||
| If a project has linked projects, any search initiated on the origin project is automatically performed on the origin project and all its linked projects. | ||
| This behavior is referred to as flat-world search. |
There was a problem hiding this comment.
#This still feels like a partial explanation. We do need to zoom out and provide a simple mental model.
I would try something like this, though we probably need better language: with CPS we are introducing a flat world name spacing for all document containers (indices, aliases, data streams, and so on)
In practical terms, this means that when you refer to an object by a name "foo", we will resolve it, not only against the origin project, but also against all of the linked projects. So for example, when you are executing a search against "logs", the search will run against all indices called "logs" across the origin and linked projects.
Something like that. Fundamentally "flat world" applies to index resolution, and we need to punch it up.
|
|
||
| ### Unqualified and qualified search expressions | ||
|
|
||
| {{cps-cap}} supports two types of search expressions: unqualified and qualified search expressions. The difference between them determines where a search request runs. |
There was a problem hiding this comment.
The thing that we are not making clear here, is that the "unqualified" is the flat world model, worse "qualified" is more of a CCS compatibility option
|
|
||
| A **qualified** search expression includes additional qualifiers, such as project prefixes or tags, that explicitly control the scope of the search. | ||
|
|
||
| Qualified search expressions enables you to: |
There was a problem hiding this comment.
I would just saw "this is CCS syntax we still support". This is not what we actually want to emphasize.
| In {{cps}}, when projects are linked to an origin project, all their searchable resources are conceptually brought into the origin project’s search scope. For search purposes, this forms a single merged project view. | ||
|
|
||
| * Unqualified index expressions are resolved against this merged project view. | ||
| * Qualified index expressions are resolved independently within each qualified project. |
There was a problem hiding this comment.
"each qualified project"? That's not clear
THIS IS WIP
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