Skip to content
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

Add documentation for security config upgrade feature #6634

Merged
merged 24 commits into from
Mar 27, 2024
Merged

Add documentation for security config upgrade feature #6634

Changes from 17 commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
31cca14
Add documentation for security config upgrade feature
peternied Mar 8, 2024
765ae9d
Merge branch 'main' into security-upgrade
Naarcha-AWS Mar 12, 2024
a779ce3
Fix vale annotations
peternied Mar 15, 2024
7f07e97
Merge remote-tracking branch 'origin/main' into security-upgrade
peternied Mar 15, 2024
3d43974
Merge branch 'main' into security-upgrade
Naarcha-AWS Mar 21, 2024
57c4605
Feedback round 1
peternied Mar 21, 2024
299a7b7
Resolve OpenSearch.SpacingPunctuation
peternied Mar 21, 2024
059b969
Fix vale error
peternied Mar 22, 2024
cc760bb
Clean up rendering of list of options for upgrade
peternied Mar 22, 2024
b5cc844
Clean up formatting around example a little
peternied Mar 22, 2024
2c759a4
Merge branch 'main' into security-upgrade
peternied Mar 22, 2024
483f499
Merge branch 'main' into security-upgrade
Naarcha-AWS Mar 22, 2024
487f805
Merge branch 'main' into security-upgrade
peternied Mar 25, 2024
1243997
PR Feedback 2
peternied Mar 26, 2024
606679c
Merge branch 'main' into security-upgrade
Naarcha-AWS Mar 26, 2024
6cfc3ad
Update api.md
Naarcha-AWS Mar 26, 2024
8e65fce
Merge branch 'main' into security-upgrade
Naarcha-AWS Mar 26, 2024
6aab4e3
Apply suggestions from code review
Naarcha-AWS Mar 26, 2024
a4d0372
Apply suggestions from code review
Naarcha-AWS Mar 26, 2024
a75aed1
Merge branch 'main' into security-upgrade
Naarcha-AWS Mar 26, 2024
a1bc78c
Update _security/access-control/api.md
Naarcha-AWS Mar 27, 2024
c2c266d
Merge branch 'main' into security-upgrade
Naarcha-AWS Mar 27, 2024
a3c9892
Merge branch 'main' into security-upgrade
Naarcha-AWS Mar 27, 2024
698542c
Update _security/access-control/api.md
Naarcha-AWS Mar 27, 2024
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
85 changes: 85 additions & 0 deletions _security/access-control/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1297,6 +1297,91 @@
}
```

### Configuration upgrade check

Introduced 2.13
{: .label .label-purple }

Checks the cuurent configuration bundled with the host's Security plugin and compares it to the latest Security plugin bundled with OpenSearch. Then, the API returns whether or not can be performed and what resources can be updated.

Check failure on line 1305 in _security/access-control/api.md

View workflow job for this annotation

GitHub Actions / style-job 

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

Raw Output:
{"message": "[OpenSearch.Spelling] Error: cuurent. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_security/access-control/api.md", "range": {"start": {"line": 1305, "column": 12}}}, "severity": "ERROR"}
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

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

There appear to be some words missing in the second sentence.

Copy link
Member Author

Choose a reason for hiding this comment

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

Original text: Checks the configuration bundled with the Security plugin against the existing security configuration, returns if an upgrade can be performed and what resources would be updated.

Here is a diagram of what the actual flow / comparisons are. (Thanks ChatGPT!)

sequenceDiagram
    participant U as User
    participant D as Configuration on Disk
    participant S as SecurityPlugin
    participant M as Configuration in SecurityPlugin Memory
    U->>+S: API Call to Check Configuration
    S->>+D: Retrieve Current Configuration from Disk
    D-->>-S: Current Disk Configuration
    S->>+M: Check Configuration in Memory
    M-->>-S: Current in Memory Configuration
    S->>S: Compare Configurations
    alt Configurations Match
        S-->>U: No Update Needed
    else Configurations Do Not Match
        S->>S: Determine Resources for Update
        S-->>U: Update Can be Performed, List resources to Update
    end
Loading

Copy link
Member Author

@peternied peternied Mar 26, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

@natebower I feel like that original text might be a better starting point, but let me know if you'd like me to workshop it more

Copy link
Collaborator

Choose a reason for hiding this comment

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

@peternied: I think I'm confused as to what you mean by "bundled"? When I hear bundled, I assume the API is checking for upgrades either against the upstream instance (The newest artifact) or the version the artifact the user downloaded. But, if the user has to download a new artifact for the latest Security Plugin information to persist in memory, isn't there a step we're missing in the documentation then?

Copy link
Member Author

Choose a reason for hiding this comment

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

I mean the version the artifact the user downloaded.

This API is for after an upgrade was performed, such as a Rolling Upgrade.

Note; I think this highlights another part of the documentation that I should include 'now that you've upgraded you can [optionally] upgrade the security configuration via this API' which links to this documentation


When a new OpenSearch version is released, there are changes to the default security configuration. This endpoint helps cluster operators check if the cluster is missing defaults or has stale definitions of defaults.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved
{: .note}

#### Request

```json
GET _plugins/_security/api/_upgrade_check
```
{% include copy-curl.html %}

#### Example response

```json
{
"status" : "OK",
"upgradeAvailable" : true,
"upgradeActions" : {
"roles" : {
"add" : [ "flow_framework_full_access" ]
}
}
}
```

#### Response fields

| Field | Data type | Description |
|:---------|:-----------|:------------------------------|
| `upgradeAvailable` | Boolean | Responds with `true` when an upgrade to the security configuration is avaliable. |

Check failure on line 1335 in _security/access-control/api.md

View workflow job for this annotation

GitHub Actions / style-job 

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

Raw Output:
{"message": "[OpenSearch.Spelling] Error: avaliable. If you are referencing a setting, variable, format, function, or repository, surround it with tic marks.", "location": {"path": "_security/access-control/api.md", "range": {"start": {"line": 1335, "column": 110}}}, "severity": "ERROR"}
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved
| `upgradeActions` | Object list | A list of security objects that would be modified if upgrading the host's Security Plugin. |

Check failure on line 1336 in _security/access-control/api.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'Security plugin' instead of 'Security Plugin'.

Raw Output:
{"message": "[Vale.Terms] Use 'Security plugin' instead of 'Security Plugin'.", "location": {"path": "_security/access-control/api.md", "range": {"start": {"line": 1336, "column": 114}}}, "severity": "ERROR"}
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

### Configuration upgrade

Introduced 2.13
{: .label .label-purple }

Adds and updates resources on a host's existing security configuration from the configuration bundled with the latest version of the Security plugin.

These bundled configuration files can be found in the `<OPENSEARCH_HOME>/security/config` directory. Default configuration files are updated on OpenSearch upgrade, whereas the cluster configuration is only updated by the cluster operators. This endpoint helps cluster operators upgrade missing defaults and stale defaults definitions.
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator

Choose a reason for hiding this comment

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

"cluster operator" (singular)?



#### Request

```json
POST _plugins/_security/api/_upgrade_perform
{
"configs" : [ "roles" ]
}
```
{% include copy-curl.html %}

#### Request fields

| Field | Data type | Description | Required |
|:----------------|:-----------|:------------------------------------------------------------------------------------------------------------------|:---------|
| `configs` | Array | Specifies the configurations to be upgraded. This field can include any combination of the following configuration:s `actiongroups`,`allowlist`, `audit`, `internalusers`, `nodesdn`, `roles`, `rolesmappings`, `tenants`.<br> Default is all supported configurations. | No |
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved


#### Example response

```json
{
"status" : "OK",
"upgrades" : {
"roles" : {
"add" : [ "flow_framework_full_access" ]
}
}
}
```

#### Response fields

| Field | Data type | Description |
|:---------|:-----------|:------------------------------|
| `upgrades` | Object | A container for the upgrade results, organized by configuration type, such as `roles`. Each configuration type that has changed will be represented as a key in this object. |
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved
| `roles` | Object | Contains a list role-based action keys of objects modified by the upgrade. |
Naarcha-AWS marked this conversation as resolved.
Show resolved Hide resolved

---

## Distinguished names
Expand Down
Loading