Skip to content

Added documentation for Experimental Security Configuration Versioning Management and APIs #10143

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Added documentation for Experimental Security Configuration Versioning Management and APIs #10143

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5845849
Added documentation for Security Configuration Versioning and Rollbac…
Jun 23, 2025
98fbb83
Merge branch 'main' into versioning
divyanshi-0402 Jun 25, 2025
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
59 changes: 59 additions & 0 deletions _security/configuration/versioning-for-security-configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Security Configuration Versioning and Rollback API

Check failure on line 1 in _security/configuration/versioning-for-security-configurations.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.HeadingCapitalization] 'Security Configuration Versioning and Rollback API' is a heading and should be in sentence case.

Raw Output:
{"message": "[OpenSearch.HeadingCapitalization] 'Security Configuration Versioning and Rollback API' is a heading and should be in sentence case.", "location": {"path": "_security/configuration/versioning-for-security-configurations.md", "range": {"start": {"line": 1, "column": 3}}}, "severity": "ERROR"}

## Overview

Check failure on line 3 in _security/configuration/versioning-for-security-configurations.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.StackedHeadings] Do not stack headings. Insert an introductory sentence between headings.

Raw Output:
{"message": "[OpenSearch.StackedHeadings] Do not stack headings. Insert an introductory sentence between headings.", "location": {"path": "_security/configuration/versioning-for-security-configurations.md", "range": {"start": {"line": 3, "column": 1}}}, "severity": "ERROR"}

OpenSearch now supports **versioning of security configurations** to improve traceability, auditability, and operational safety. Each update to critical security configurations is tracked as a new version, and users can view or roll back to any previous version via the dedicated APIs.

Check warning on line 5 in _security/configuration/versioning-for-security-configurations.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.LatinismsSubstitution] Use 'using, through, by accessing, or by choosing' instead of 'via'.

Raw Output:
{"message": "[OpenSearch.LatinismsSubstitution] Use 'using, through, by accessing, or by choosing' instead of 'via'.", "location": {"path": "_security/configuration/versioning-for-security-configurations.md", "range": {"start": {"line": 5, "column": 263}}}, "severity": "WARNING"}

Check failure on line 5 in _security/configuration/versioning-for-security-configurations.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.Spelling] Error: auditability. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.

Raw Output:
{"message": "[OpenSearch.Spelling] Error: auditability. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_security/configuration/versioning-for-security-configurations.md", "range": {"start": {"line": 5, "column": 92}}}, "severity": "ERROR"}

This documentation covers:
- How versioning works
- How to use the View API to inspect past versions
- How to use the Rollback API to restore configurations

---

## 1. Versioning Overview

Check failure on line 14 in _security/configuration/versioning-for-security-configurations.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.HeadingCapitalization] '1. Versioning Overview' is a heading and should be in sentence case.

Raw Output:
{"message": "[OpenSearch.HeadingCapitalization] '1. Versioning Overview' is a heading and should be in sentence case.", "location": {"path": "_security/configuration/versioning-for-security-configurations.md", "range": {"start": {"line": 14, "column": 4}}}, "severity": "ERROR"}

### What is versioned?

Check failure on line 16 in _security/configuration/versioning-for-security-configurations.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.HeadingPunctuation] Don't use punctuation at the end of a heading.

Raw Output:
{"message": "[OpenSearch.HeadingPunctuation] Don't use punctuation at the end of a heading.", "location": {"path": "_security/configuration/versioning-for-security-configurations.md", "range": {"start": {"line": 16, "column": 22}}}, "severity": "ERROR"}

Check failure on line 16 in _security/configuration/versioning-for-security-configurations.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.StackedHeadings] Do not stack headings. Insert an introductory sentence between headings.

Raw Output:
{"message": "[OpenSearch.StackedHeadings] Do not stack headings. Insert an introductory sentence between headings.", "location": {"path": "_security/configuration/versioning-for-security-configurations.md", "range": {"start": {"line": 16, "column": 1}}}, "severity": "ERROR"}

Any supported security configuration update is captured as a new version. A version includes:
- Snapshot of the full security configuration at that time
- A unique version ID (e.g., `v1`, `v2`, ...)
- Timestamp of creation
- User who performed the update

### When is a new version created?

Check failure on line 24 in _security/configuration/versioning-for-security-configurations.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.HeadingPunctuation] Don't use punctuation at the end of a heading.

Raw Output:
{"message": "[OpenSearch.HeadingPunctuation] Don't use punctuation at the end of a heading.", "location": {"path": "_security/configuration/versioning-for-security-configurations.md", "range": {"start": {"line": 24, "column": 34}}}, "severity": "ERROR"}

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.

---

## 2. View Version API

Check failure on line 30 in _security/configuration/versioning-for-security-configurations.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.HeadingCapitalization] '2. View Version API' is a heading and should be in sentence case.

Raw Output:
{"message": "[OpenSearch.HeadingCapitalization] '2. View Version API' is a heading and should be in sentence case.", "location": {"path": "_security/configuration/versioning-for-security-configurations.md", "range": {"start": {"line": 30, "column": 4}}}, "severity": "ERROR"}

Purpose: View the complete history of security configuration changes, or any specific version of the security configurations.

### Endpoint:
- To view all the versions : GET /_plugins/_security/api/versions
- To view a specific version : GET /_plugins/_security/api/version/{versionId}

Access Control: Admin/Security Manager permissions required

## 3. Rollback Version API

Check failure on line 40 in _security/configuration/versioning-for-security-configurations.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.HeadingCapitalization] '3. Rollback Version API' is a heading and should be in sentence case.

Raw Output:
{"message": "[OpenSearch.HeadingCapitalization] '3. Rollback Version API' is a heading and should be in sentence case.", "location": {"path": "_security/configuration/versioning-for-security-configurations.md", "range": {"start": {"line": 40, "column": 4}}}, "severity": "ERROR"}

Purpose : Allows rollback to immediate or any desired version of security

### Endpoint:
- To rollback to immediate previous version : POST /_plugins/_security/api/version/rollback
- To rollback to a specific version : POST /_plugins/_security/api/version/rollback/{versionID}

Access Control: Admin/Security Manager permissions required

## 4. Enabling the Feature

* To enable this feature, add the following setting to your `opensearch.yml` file:
```bash
plugins.security.configurations_versions.enabled: true
```
* Optional: Control how many versions are retained using:
```bash
plugins.security.config_version.retention_count: 10
```
Loading