Skip to content

Commit b1741e8

Browse files
szabosteveleemthompo
szabosteve
and
leemthompo
authored
DOCS] Adds update cross cluster API key API examples (#129843)
* DOCS] Adds update cross cluster API k ey API examples. * Fixes markup. * Update docs/reference/elasticsearch/rest-apis/update-cc-api-key-examples.md Co-authored-by: Liam Thompson <[email protected]> * [DOCS] Subheadings. --------- Co-authored-by: Liam Thompson <[email protected]>
1 parent 11ca4f6 commit b1741e8

File tree

2 files changed

+212
-0
lines changed

2 files changed

+212
-0
lines changed

‎docs/reference/elasticsearch/rest-apis/update-cc-api-key-examples.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
---
2+
applies_to:
3+
stack: all
4+
navigation_title: Update cross-cluster API examples
5+
---
6+
# Update cross-cluster API key API examples
7+
8+
The [update cross-cluster API key API](https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation/operation-security-update-cross-cluster-api-key) updates the attributes of an existing cross-cluster API key, which is used for API key based remote cluster access. This page shows you examples of using this API.
9+
10+
## Create a cross-cluster API key
11+
12+
If you create a cross-cluster API key as follows:
13+
14+
```console
15+
POST /_security/cross_cluster/api_key
16+
{
17+
"name": "my-cross-cluster-api-key",
18+
"access": {
19+
"search": [
20+
{
21+
"names": ["logs*"]
22+
}
23+
]
24+
},
25+
"metadata": {
26+
"application": "search"
27+
}
28+
}
29+
```
30+
31+
A successful call returns a JSON structure that provides API key information. For example:
32+
33+
```console-result
34+
{
35+
"id": "VuaCfGcBCdbkQm-e5aOx",
36+
"name": "my-cross-cluster-api-key",
37+
"api_key": "ui2lp2axTNmsyakw9tvNnw",
38+
"encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
39+
}
40+
```
41+
42+
% TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
43+
% TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/]
44+
% TESTRESPONSE[s/VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==/$body.encoded/]
45+
46+
## Inspect the API key
47+
48+
To retrieve key information about the API key, including the exact role descriptor, use the [Get API key API](https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation/operation-security-get-api-key).
49+
50+
```console
51+
GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx
52+
```
53+
54+
% TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
55+
% TEST[continued]
56+
57+
A successful call returns a JSON structure that contains the information of the API key:
58+
59+
```js
60+
{
61+
"api_keys": [
62+
{
63+
"id": "VuaCfGcBCdbkQm-e5aOx",
64+
"name": "my-cross-cluster-api-key",
65+
"type": "cross_cluster",
66+
"creation": 1548550550158,
67+
"expiration": null,
68+
"invalidated": false,
69+
"username": "myuser",
70+
"realm": "native1",
71+
"metadata": {
72+
"application": "search"
73+
},
74+
"role_descriptors": {
75+
"cross_cluster": { <1>
76+
"cluster": [
77+
"cross_cluster_search"
78+
],
79+
"indices": [
80+
{
81+
"names": [
82+
"logs*"
83+
],
84+
"privileges": [
85+
"read", "read_cross_cluster", "view_index_metadata"
86+
],
87+
"allow_restricted_indices": false
88+
}
89+
],
90+
"applications": [ ],
91+
"run_as": [ ],
92+
"metadata": { },
93+
"transient_metadata": {
94+
"enabled": true
95+
}
96+
}
97+
},
98+
"access": { <2>
99+
"search": [
100+
{
101+
"names": [
102+
"logs*"
103+
],
104+
"allow_restricted_indices": false
105+
}
106+
]
107+
}
108+
}
109+
]
110+
}
111+
```
112+
113+
% NOTCONSOLE
114+
115+
1. Role descriptor corresponding to the specified `access` scope at creation time.
116+
In this example, it grants cross cluster search permission for the `logs*` index pattern.
117+
2. The `access` corresponds to the value specified at API key creation time.
118+
119+
## Update access permissions and metadata
120+
121+
The following example updates the API key created above, assigning it new access scope and metadata:
122+
123+
```console
124+
PUT /_security/cross_cluster/api_key/VuaCfGcBCdbkQm-e5aOx
125+
{
126+
"access": {
127+
"replication": [
128+
{
129+
"names": ["archive"]
130+
}
131+
]
132+
},
133+
"metadata": {
134+
"application": "replication"
135+
}
136+
}
137+
```
138+
139+
% TEST[s/VuaCfGcBCdbkQm-e5aOx/\${body.api_keys.0.id}/]
140+
% TEST[continued]
141+
142+
A successful call returns a JSON structure indicating that the API key was updated:
143+
144+
```console-result
145+
{
146+
"updated": true
147+
}
148+
```
149+
150+
The API key's permissions after the update can be inspected again with the [Get API key API](https://www.elastic.co/docs/api/doc/elasticsearch/v9/operation/operation-security-get-api-key) and it will be:
151+
152+
```js
153+
{
154+
"api_keys": [
155+
{
156+
"id": "VuaCfGcBCdbkQm-e5aOx",
157+
"name": "my-cross-cluster-api-key",
158+
"type": "cross_cluster",
159+
"creation": 1548550550158,
160+
"expiration": null,
161+
"invalidated": false,
162+
"username": "myuser",
163+
"realm": "native1",
164+
"metadata": {
165+
"application": "replication"
166+
},
167+
"role_descriptors": {
168+
"cross_cluster": { <1>
169+
"cluster": [
170+
"cross_cluster_replication"
171+
],
172+
"indices": [
173+
{
174+
"names": [
175+
"archive*"
176+
],
177+
"privileges": [
178+
"cross_cluster_replication", "cross_cluster_replication_internal"
179+
],
180+
"allow_restricted_indices": false
181+
}
182+
],
183+
"applications": [ ],
184+
"run_as": [ ],
185+
"metadata": { },
186+
"transient_metadata": {
187+
"enabled": true
188+
}
189+
}
190+
},
191+
"access": { <2>
192+
"replication": [
193+
{
194+
"names": [
195+
"archive*"
196+
],
197+
"allow_restricted_indices": false
198+
}
199+
]
200+
}
201+
}
202+
]
203+
}
204+
```
205+
206+
% NOTCONSOLE
207+
208+
1. Role descriptor is updated to be the `access` scope specified at update time.
209+
In this example, it is updated to grant the cross cluster replication permission
210+
for the `archive*` index pattern.
211+
2. The `access` corresponds to the value specified at API key update time.

‎docs/reference/elasticsearch/toc.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,7 @@ toc:
104104
- file: rest-apis/searching-with-query-rules.md
105105
- file: rest-apis/shard-request-cache.md
106106
- file: rest-apis/term-vectors-examples.md
107+
- file: rest-apis/update-cc-api-key-examples.md
107108
- file: mapping-reference/index.md
108109
children:
109110
- file: mapping-reference/document-metadata-fields.md

0 commit comments

Comments
 (0)