Skip to content

Commit 626bad6

Browse files
nagarajg17Divyanshi Choukseykolchfa-awsnatebower
authored
Add documentation for Experimental Security Configuration Versioning Management and APIs (#11195)
* Added documentation for Security Configuration Versioning and Rollback API Signed-off-by: Divyanshi Chouksey <[email protected]> * Doc review Signed-off-by: Fanit Kolchina <[email protected]> * Add documentation for Experimental Security Configuration Versioning Management and its APIs Signed-off-by: Nagaraj G <[email protected]> * Doc review Signed-off-by: Fanit Kolchina <[email protected]> * Apply suggestions from code review Signed-off-by: Nathan Bower <[email protected]> * Apply suggestions from code review Signed-off-by: kolchfa-aws <[email protected]> * Update _security/configuration/versioning.md Signed-off-by: kolchfa-aws <[email protected]> --------- Signed-off-by: Divyanshi Chouksey <[email protected]> Signed-off-by: Fanit Kolchina <[email protected]> Signed-off-by: Nagaraj G <[email protected]> Signed-off-by: Nathan Bower <[email protected]> Signed-off-by: kolchfa-aws <[email protected]> Co-authored-by: Divyanshi Chouksey <[email protected]> Co-authored-by: Fanit Kolchina <[email protected]> Co-authored-by: Nathan Bower <[email protected]> Co-authored-by: kolchfa-aws <[email protected]>
1 parent afad63a commit 626bad6

File tree

1 file changed

+225
-0
lines changed

1 file changed

+225
-0
lines changed

‎_security/configuration/versioning.md‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
---
2+
layout: default
3+
title: Security configuration versioning
4+
parent: Configuration
5+
nav_order: 27
6+
---
7+
8+
# Security Configuration Versioning and Rollback API
9+
**Introduced 3.3**
10+
{: .label .label-purple }
11+
12+
This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, join the discussion on the [OpenSearch forum](https://forum.opensearch.org/).
13+
{: .warning}
14+
15+
The Security Configuration Versioning and Rollback API provides version control for OpenSearch security configurations, enabling administrators to track changes, maintain audit trails, and restore previous configurations when needed.
16+
17+
This API automatically creates versions when security configurations change, allowing you to track the complete history of security configuration modifications, view detailed information about any previous version, and roll back to any previous configuration version, thus maintaining operational safety.
18+
19+
## How versioning works
20+
21+
The system automatically creates a new version when a security configuration change is detected, the change differs from the most recent saved version, and an administrator makes modifications through supported APIs.
22+
23+
Each version contains a version ID (unique identifier such as `v1`, `v2`), a configuration snapshot (complete security configuration at the time of creation), a timestamp indicating when the version was created, and user information identifying who made the change.
24+
25+
A new version is created **only when a change is detected** compared to the latest saved version. This prevents redundant versions and ensures meaningful version history.
26+
27+
## Enabling versioning
28+
29+
To use the security configuration versioning, you must enable it in your OpenSearch configuration. Add the following setting to your `opensearch.yml` configuration file:
30+
31+
```yaml
32+
plugins.security.configurations_versions.enabled: true
33+
```
34+
35+
Optionally, you can control the number of retained versions by specifying the following setting:
36+
37+
```yaml
38+
plugins.security.config_version.retention_count: 10
39+
```
40+
41+
The default retention count is `10` versions. When the retention limit is reached, the oldest version is automatically removed to make space for one new version.
42+
43+
After modifying `opensearch.yml`, restart your OpenSearch cluster for the changes to take effect. For more information, see [Experimental feature flags]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/experimental/).
44+
45+
## Endpoints
46+
47+
```json
48+
GET /_plugins/_security/api/versions
49+
GET /_plugins/_security/api/version/<version_id>
50+
POST /_plugins/_security/api/version/rollback
51+
POST /_plugins/_security/api/version/rollback/<version_id>
52+
```
53+
54+
## Path parameters
55+
56+
The following table lists the available path parameters. All path parameters are optional.
57+
58+
| Parameter | Data type | Description |
59+
| :--- | :--- | :--- |
60+
| `version_id` | String | The version identifier to view or roll back to. Must start with `v` followed by a number (for example, `v1` or `v2`). Required for specific version operations. |
61+
62+
## View a specific version
63+
64+
Use this endpoint to retrieve the complete security configuration for a specified version.
65+
66+
### Endpoint
67+
68+
```json
69+
GET /_plugins/_security/api/version/<version_id>
70+
```
71+
72+
### Example request
73+
74+
```json
75+
GET /_plugins/_security/api/version/v2
76+
```
77+
{% include copy-curl.html %}
78+
79+
### Example response
80+
81+
```json
82+
{
83+
"versions": [
84+
{
85+
"version_id": "v2",
86+
"timestamp": "2025-05-23T06:56:20.081933886Z",
87+
"modified_by": "admin",
88+
"security_configs": {...}
89+
}
90+
]
91+
}
92+
```
93+
94+
### Response body fields
95+
96+
The following table lists all response body fields for viewing a specific version.
97+
98+
| Field | Data type | Description |
99+
|:-----------------|:----------|:------------------------------------------------------------------------------------------|
100+
| `versions` | Array | A list of security configuration versions. |
101+
| `version_id` | String | The ID of the security configuration version. |
102+
| `timestamp` | Datetime | The timestamp of the security configuration change. |
103+
| `modified_by` | String | The user who modified the security configuration. |
104+
| `security_configs` | String | The security configuration for a particular version that contains all security configurations. |
105+
106+
## View all versions
107+
108+
Use this endpoint to retrieve a list of all available configuration versions.
109+
110+
### Endpoint
111+
112+
```json
113+
GET /_plugins/_security/api/versions
114+
```
115+
116+
### Example request
117+
118+
```json
119+
GET /_plugins/_security/api/versions
120+
```
121+
{% include copy-curl.html %}
122+
123+
### Example response
124+
125+
```json
126+
{
127+
"versions": [
128+
{
129+
"version_id": "v1",
130+
"timestamp": "2025-05-22T08:46:11.887620466Z",
131+
"modified_by": "admin",
132+
"security_configs": {...}
133+
},
134+
{
135+
"version_id": "v2",
136+
"timestamp": "2025-05-23T06:56:20.081933886Z",
137+
"modified_by": "admin",
138+
"security_configs": {...}
139+
}
140+
]
141+
}
142+
```
143+
144+
### Response body fields
145+
146+
See [View a specific version response body fields](#response-body-fields).
147+
148+
## Roll back to the preceding version
149+
150+
Use this endpoint to restore the security configuration to the immediately preceding version.
151+
152+
### Endpoint
153+
154+
```json
155+
POST /_plugins/_security/api/version/rollback
156+
```
157+
158+
### Example request
159+
160+
```json
161+
POST /_plugins/_security/api/version/rollback
162+
```
163+
{% include copy-curl.html %}
164+
165+
### Example response
166+
167+
OpenSearch sends the following response when rolling back to the `v4` version from the `v5` version:
168+
169+
```json
170+
{
171+
"status" : "OK",
172+
"message" : "config rolled back to version v4"
173+
}
174+
```
175+
176+
### Response body fields
177+
178+
The following table lists all response body fields for rollback operations.
179+
180+
| Field | Data type | Description |
181+
| :--- | :--- | :--- |
182+
| `status` | String | The rollback status. |
183+
| message | String | The rollback operation description. |
184+
185+
## Roll back to a specific version
186+
187+
Use this endpoint to restore the security configuration to a specified version.
188+
189+
### Endpoint
190+
191+
```json
192+
POST /_plugins/_security/api/version/rollback/<version_id>
193+
```
194+
195+
### Example request
196+
197+
```json
198+
POST /_plugins/_security/api/version/rollback/v2
199+
```
200+
{% include copy-curl.html %}
201+
202+
### Example response
203+
204+
```json
205+
{
206+
"status" : "OK",
207+
"message" : "config rolled back to version v2"
208+
}
209+
```
210+
211+
### Response body fields
212+
213+
See [Roll back to a specific version response body fields](#response-body-fields-2).
214+
215+
## Required permissions
216+
217+
Ensure that you have the appropriate permissions for the operations you want to perform.
218+
219+
| Operation | Required permission |
220+
| :--- | :--- |
221+
| View versions | `restapi:admin/view_version` |
222+
| Roll back configuration | `restapi:admin/rollback_version` |
223+
224+
These permissions are included in the default `security_manager` and `all_access` roles.
225+
These APIs use the same [access control]({{site.url}}{{site.baseurl}}/security/access-control/api/#access-control-for-the-api) as all other Security APIs.

0 commit comments

Comments
 (0)