Rehome CCS/CCR permissions#6934
Conversation
Elastic Docs AI PR menuCheck the box to run an AI review for this pull request.
Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team. |
✅ Elastic Docs Style Checker (Vale)No issues found on modified lines! 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. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Docs review summary
Focus areas
- Style and clarity: One typo and one Vale wordiness suggestion in the new CCS section (see inline comments). Other Vale findings in changed files (
may,disabled,Disable,and/or, menu arrows) are all in pre-existing, untouched lines. - Jargon: No new jargon issues.
CCS,CCR,API key, andTLSare all adequately contextualised in the new content. - Frontmatter and applies_to: The CCR file's
applies_tochange from the verbosedeployment: eck/ess/ece/selftostack: allis valid and consistent with repo usage. Inline{applies_to}directives on the deprecated TLS cert sections are correctly applied. - Content type fit: The restructuring works. The CCS page was already a reference/how-to hybrid; adding the privilege section fits its existing shape and reader needs.
- Parent issue satisfaction: Based on the PR description, the stated goals (move privilege config out of setup pages into feature pages, slim down setup pages, update links) appear satisfied. The detection rules link update introduces a content accuracy issue worth fixing before merge (see inline comment on line 30).
Nits
cross-cluster-search.mdline 133: Therun_asprivilege in the new TLS cert subsection is plain backtick text, while the parallel CCR file links it to the privilege docs (`(reference/redacted) Consider linking for consistency.cross-cluster-search.mdline 110: "Note that you only need to create this user on the local cluster." uses informal prose while line 176–178 uses a formal::::{note}admonition for the same information in the adjacent TLS section. Minor inconsistency.
Generated by Docs review agent for issue #6934 · 419.8 AIC · ⌖ 25.4 AIC · ⊞ 32.8K
eedugon
left a comment
eedugon
left a comment
There was a problem hiding this comment.
I've only had time to review the snippet. Sharing a comment about it. As it's a snippet used in a lot of pages I think we should give a bit of extra love to it, and also mention the TLS cert-based authentication possibility.
eedugon
left a comment
eedugon
left a comment
There was a problem hiding this comment.
I've suggested some changes, I think it's a good time to refine and enhance some of the content at the same time as doing this movement.
I think the suggested changes are low effort, but feel free to ignore any of them as we could leave them for a later stage.
| #### {{kib}} users [configure-privileges-for-ccs-kibana-cert] | ||
|
|
||
| When using {{kib}} to search across multiple clusters, a two-step authorization process determines whether the user can access data streams and indices on a remote cluster: | ||
|
|
||
| * First, the local cluster determines if the user is authorized to access remote clusters. The local cluster is the cluster that {{kib}} is connected to. | ||
| * If the user is authorized, the remote cluster then determines if the user has access to the specified data streams and indices. | ||
|
|
||
| To grant {{kib}} users access to remote clusters, assign them a local role with read privileges to indices on the remote clusters. You specify data streams and indices in a remote cluster as `<remote_cluster_name>:<target>`. | ||
|
|
||
| To grant users read access on the remote data streams and indices, you must create a matching role on the remote clusters that grants the `read_cross_cluster` privilege with access to the appropriate data streams and indices. | ||
|
|
||
| For example, you might be actively indexing {{ls}} data on a local cluster and periodically offload older time-based indices to an archive on your remote cluster. You want to search across both clusters, so you must enable {{kib}} users on both clusters. | ||
|
|
||
| On the local cluster, create a `logstash-reader` role that grants `read` and `view_index_metadata` privileges on the local `logstash-*` indices. | ||
|
|
||
| ::::{note} | ||
| If you configure the local cluster as another remote in {{es}}, the `logstash-reader` role on your local cluster also needs to grant the `read_cross_cluster` privilege. | ||
| :::: | ||
|
|
||
| ```console | ||
| POST /_security/role/logstash-reader | ||
| { | ||
| "indices": [ | ||
| { | ||
| "names": [ | ||
| "logstash-*" | ||
| ], | ||
| "privileges": [ | ||
| "read", | ||
| "view_index_metadata" | ||
| ] | ||
| } | ||
| ] | ||
| } |
There was a problem hiding this comment.
Kibana users section feels misleading at first sight! (I know this comes from the old Elasticsearch doc, but it's super old).
It makes the reader to think those users could be different to the users mentioned previously, or that Kibana changes any of this in the way it works, when it doesn't!
We need to clarify the scope in the introduction better, if this is needed at all. The only benefit this section gives is to tell users that they can "REUSE" the role to grant specific privileges on the local cluster (like kibana access + indices read on the local cluster), and in the previous example we used an EMPTY ROLE in the local cluster. And that's pretty obvious and could be covered by a note or something.
^^ That's the only benefit / use case, so I wouldn't create all this "kibana users section" under the deprecated TLS cert-based authentication and instead integrate that possibility in the previous block (actually the user could create an extra role for local resources instead of doing this "hack" but anyway).
-
Also note that the concept that section covers is also applicable to the API key based auth, they could reuse the role to give local privileges.
-
Also note that the order of the role creation is different here: we start with the local role and we end up with the remote cluster role.
Conclussions:
-
I think it's time to simplify this by removing this entire section and just enrich the previous ones.
-
We could include a similar concept to the API-key based authentication: it's a bit obvious but we can remind readers that the user on the local cluster could also have privileges to the local cluster indices and resources with other roles (or the same role) (obvious IMO and the only purpose of this section).
There was a problem hiding this comment.
Okay, I think I get it. I've made changes in 42ad41e that hopefully address this.
| anchors: | ||
| 'enable-elastic-capabilities': 'elastic-capabilities' | ||
|
|
||
| # Rehome CCS and CCR privileges from remote-clusters-cert.md |
There was a problem hiding this comment.
Impressive work with redirections here!
There was a problem hiding this comment.
Was really easy to do with Cursor, so I'm afraid I can't take much credit for this specific task. Previous encounters with redirects gave me nightmares 😂
|
Hi @eedugon, thank you so much for your insightful review, really appreciate it! 💡 🙏 I think I've addressed your feedback and this is ready for another round of reviews whenever you get the chance. Many thanks in advance! 😸 |
2 participants
Summary
Fixes #436 and #6810
This PR moves the cross-cluster privilege configuration out of the remote cluster setup pages and into the feature pages of CCR and CCS where readers actually need it.
Generative AI disclosure
Used Cursor's Auto Agent mode to validate some concepts and find links to update. Also super handy way to create the necessary redirects.