Skip to content

Fix missing remote_cluster docs #116366

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 7, 2024
Merged

Fix missing remote_cluster docs #116366

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions docs/reference/modules/cluster/remote-clusters-migration.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,10 +66,11 @@ indices that were created from the auto-follow pattern.
On the local cluster:

. Enhance any roles used by local cluster users with the required
<<roles-remote-indices-priv,remote indices privileges>> for {ccr} and {ccs}.
<<roles-remote-indices-priv,remote indices privileges>> or
<<roles-remote-cluster-priv, remote cluster privileges>> for {ccr} and {ccs}.
Refer to <<remote-clusters-privileges-api-key>>. Note:

** You only need to assign additional `remote_indices` privileges to existing
** You only need to assign additional `remote_indices` or `remote_cluster` privileges to existing
roles used for cross-cluster operations. You should be able to copy these
privileges from the original roles on the remote cluster, where they are defined
under the certification based security model.
Expand Down Expand Up @@ -197,7 +198,7 @@ authentication.
Resume any persistent tasks that you stopped earlier. Tasks should be restarted
by the same user or API key that created the task before the migration. Ensure
the roles of this user or API key have been updated with the required
`remote_indices` privileges. For users, tasks capture the caller's credentials
`remote_indices` or `remote_cluster` privileges. For users, tasks capture the caller's credentials
when started and run in that user's security context. For API keys, restarting a
task will update the task with the updated API key.

Expand Down Expand Up @@ -246,7 +247,7 @@ If you need to roll back, follow these steps on the local cluster:
. Remove the remote cluster definition by setting the remote cluster settings to
`null`.

. Remove the `remote_indices` privileges from any roles that were updated during
. Remove the `remote_indices` or 'remote_cluster' privileges from any roles that were updated during
the migration.

. On each node, remove the `remote_cluster_client.ssl.*` settings from
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/modules/cluster/remote-clusters-troubleshooting.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -399,7 +399,7 @@ This does not show up in any logs.

====== Resolution

. Check that the local user has the necessary `remote_indices` privileges. Grant sufficient `remote_indices` privileges if necessary.
. Check that the local user has the necessary `remote_indices` or `remote_cluster` privileges. Grant sufficient `remote_indices` or `remote_cluster` privileges if necessary.
. If permission is not an issue locally, ask the remote cluster administrator to
create and distribute a
<<security-api-create-cross-cluster-api-key,cross-cluster API key>>. Replace the
Expand Down
14 changes: 13 additions & 1 deletion docs/reference/rest-api/security/bulk-create-roles.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ that begin with `_` are reserved for system usage.
For more information, see
<<run-as-privilege>>.

`remote_indices`:: beta:[] (list) A list of remote indices permissions entries.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice catch!

`remote_indices`:: (list) A list of remote indices permissions entries.
+
--
NOTE: Remote indices are effective for <<remote-clusters-api-key,remote clusters configured with the API key based model>>.
Expand All @@ -94,6 +94,18 @@ have on the specified indices.
read access to. A document within the specified indices must match this query in
order for it to be accessible by the owners of the role.

`remote_cluster`:: (list) A list of remote cluster permissions entries.
+
--
NOTE: Remote cluster permissions are effective for <<remote-clusters-api-key,remote clusters configured with the API key based model>>.
They have no effect for remote clusters configured with the <<remote-clusters-cert,certificate based model>>.
--
`clusters` (required)::: (list) A list of cluster aliases to which the permissions
in this entry apply.
`privileges`(required)::: (list) The cluster level privileges that the owners of the role
have in the specified clusters.


For more information, see <<defining-roles>>.
====

Expand Down
11 changes: 11 additions & 0 deletions docs/reference/rest-api/security/create-roles.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,17 @@ have on the specified indices.
read access to. A document within the specified indices must match this query in
order for it to be accessible by the owners of the role.

`remote_cluster`:: (list) A list of remote cluster permissions entries.
+
--
NOTE: Remote cluster permissions are effective for <<remote-clusters-api-key,remote clusters configured with the API key based model>>.
They have no effect for remote clusters configured with the <<remote-clusters-cert,certificate based model>>.
--
`clusters` (required)::: (list) A list of cluster aliases to which the permissions
in this entry apply.
`privileges`(required)::: (list) The cluster level privileges that the owners of the role
have in the specified clusters.

For more information, see <<defining-roles>>.

[[security-api-put-role-example]]
Expand Down
5 changes: 3 additions & 2 deletions docs/reference/security/authentication/remote-clusters-privileges-api-key.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@
=== Configure roles and users

To use a remote cluster for {ccr} or {ccs}, you need to create user roles with
<<roles-remote-indices-priv,remote indices privileges>> on the local cluster.
<<roles-remote-indices-priv,remote indices privileges>> or
<<roles-remote-cluster-priv, remote cluster privileges>> on the local cluster.

You can manage users and roles from Stack Management in {kib} by selecting
*Security > Roles* from the side navigation. You can also use the
Expand Down Expand Up @@ -80,7 +81,7 @@ POST /_security/role/remote-search
"privileges": [
"read",
"read_cross_cluster",
"view_index_metadata"
"view_index_metadata"
]
}
]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wondering if we should update example remote-search role to include remote cluster privileges?

Suggested change
]
],
"remote_cluster": [
{
"privileges": [
"monitor_enrich"
],
"clusters": [
"my_remote_cluster"
]
}
]

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not yet. This PR backfills some missing docs and will target elder docs where monitor_enrich is the privilege allowed (that usage is already covered in ES|QL docs where it is relevant). I will have another docs PR to introduce a new remote_cluster privilege and will consider it then.

Expand Down
Loading