Graduate resource sharing feature out of experimental

RESOURCE_SHARING_AND_ACCESS_CONTROL.md

@@ -30,7 +30,7 @@ The **Resource Sharing and Access Control** feature in OpenSearch Security Plugi
 
 This feature ensures **secure** and **controlled** access to shareableResources while leveraging existing **index-level authorization** in OpenSearch.
 
-NOTE: This feature is marked as **`@opensearch.experimental`** and can be toggled using the feature flag: **`plugins.security.experimental.resource_sharing.enabled`**, which is **disabled by default**.
+NOTE: This feature can be toggled using the feature flag: **`plugins.security.resource_sharing.enabled`**, which is **disabled by default**.
 
 
 ## **2. What are the Components?**
@@ -142,8 +142,8 @@ integTest {
     ...
     node.setting("plugins.security.system_indices.enabled", "true")
     if (System.getProperty("resource_sharing.enabled") == "true") {
-        node.setting("plugins.security.experimental.resource_sharing.enabled", "true")
-        node.setting("plugins.security.experimental.resource_sharing.protected_types", "[\"anomaly-detector\", \"forecaster\"]")
+        node.setting("plugins.security.resource_sharing.enabled", "true")
+        node.setting("plugins.security.resource_sharing.protected_types", "[\"anomaly-detector\", \"forecaster\"]")
     }
     ...
 }
@@ -474,8 +474,8 @@ Since no entities are listed, the resource is accessible **only by its creator a
 
 
 ### **Additional Notes**
-- **Feature Flag:** These APIs are available only when `plugins.security.experimental.resource_sharing.enabled` is set to `true` in the configuration.
-- **Protected Types:** These APIs will only come into effect if concerned resources are marked as protected: `plugins.security.experimental.resource_sharing.protected_types: [<type-1>, <type-2>]`.
+- **Feature Flag:** These APIs are available only when `plugins.security.resource_sharing.enabled` is set to `true` in the configuration.
+- **Protected Types:** These APIs will only come into effect if concerned resources are marked as protected: `plugins.security.resource_sharing.protected_types: [<type-1>, <type-2>]`.
 
 ---
 
@@ -487,21 +487,28 @@ Since no entities are listed, the resource is accessible **only by its creator a
 ### **Feature Flag**
 This feature is controlled by the following flag:
 
-- **Feature flag:** `plugins.security.experimental.resource_sharing.enabled`
+- **Feature flag:** `plugins.security.resource_sharing.enabled`
 - **Default value:** `false`
 - **How to enable?** Set the flag to `true` in the opensearch configuration:
   ```yaml
-  plugins.security.experimental.resource_sharing.enabled: true
+  plugins.security.resource_sharing.enabled: true
   ```
+> **Upgrading from a version that used the experimental flag (breaking change)**
+>
+> Prior to graduation, these settings were named `plugins.security.experimental.resource_sharing.enabled` and `plugins.security.experimental.resource_sharing.protected_types`. The `experimental.` segment has been **removed with no fallback**, so the old keys no longer work. Before upgrading:
+> - **`opensearch.yml`:** rename the keys to the new names on every node. A node that still has an old `plugins.security.experimental.resource_sharing.*` key will **fail to start** (`unknown setting`).
+> - **Persistent cluster settings:** re-apply the setting under the new key after upgrading. On upgrade the old key is no longer recognized and is archived (`archived.plugins.security.experimental.resource_sharing.*`), so the feature reverts to its default (**disabled**) until you re-apply it.
+> - **During a rolling upgrade**, enforcement is inconsistent until all nodes are on the new version: the new key is rejected by not-yet-upgraded nodes and the old key by upgraded nodes. Plan for resource sharing to be effectively disabled in this window and re-apply the setting once the upgrade completes.
+
 ### **List protected types**
 
 The list of protected types are controlled through following opensearch setting
 
-- **Setting:** `plugins.security.experimental.resource_sharing.protected_types`
+- **Setting:** `plugins.security.resource_sharing.protected_types`
 - **Default value:** `[]`
 - **How to specify a type?** Add entries of existing types in the list:
   ```yaml
-  plugins.security.experimental.resource_sharing.protected_types: [sample-resource]
+  plugins.security.resource_sharing.protected_types: [sample-resource]
   ```
 NOTE: These types will be available on documentation website.
 
@@ -516,7 +523,7 @@ This allows administrators to enable or disable the **Resource Sharing** feature
 PUT _cluster/settings
 {
   "transient": {
-    "plugins.security.experimental.resource_sharing.enabled": true
+    "plugins.security.resource_sharing.enabled": true
   }
 }
 ```
@@ -527,7 +534,7 @@ PUT _cluster/settings
 PUT _cluster/settings
 {
   "transient": {
-    "plugins.security.experimental.resource_sharing.protected_types": ["sample-resource", "ml-model"]
+    "plugins.security.resource_sharing.protected_types": ["sample-resource", "ml-model"]
   }
 }
 ```
@@ -538,7 +545,7 @@ PUT _cluster/settings
 PUT _cluster/settings
 {
   "transient": {
-    "plugins.security.experimental.resource_sharing.protected_types": []
+    "plugins.security.resource_sharing.protected_types": []
   }
 }
 ```

spi/src/main/java/org/opensearch/security/spi/resources/ResourceProvider.java

@@ -11,8 +11,6 @@
 /**
  * This record class represents a resource provider.
  * It holds information about the resource type, resource index name, and a resource parser.
- *
- * @opensearch.experimental
  */
 public interface ResourceProvider {
 

spi/src/main/java/org/opensearch/security/spi/resources/ResourceSharingExtension.java

@@ -18,8 +18,6 @@
  * This interface should be implemented by all the plugins that define one or more resources and need access control over those resources.
  * Extends {@link SecurityConfigExtension} so resource-sharing plugins can also contribute static security configuration
  * (e.g. default roles via {@code default-roles.yml}).
- *
- * @opensearch.experimental
  */
 public interface ResourceSharingExtension extends SecurityConfigExtension {
 

spi/src/main/java/org/opensearch/security/spi/resources/client/ResourceSharingClient.java

@@ -14,8 +14,6 @@
 
 /**
  * Interface for resource sharing client operations.
- *
- * @opensearch.experimental
  */
 public interface ResourceSharingClient {
 

spi/src/main/java/org/opensearch/security/spi/resources/client/package-info.java

@@ -8,8 +8,6 @@
 
 /**
  * This package defines a resource sharing client that will be utilized by resource plugins to implement resource access control.
- *
- * @opensearch.experimental
  */
 
 package org.opensearch.security.spi.resources.client;

spi/src/main/java/org/opensearch/security/spi/resources/package-info.java

@@ -9,7 +9,5 @@
 /**
  * This package defines classes required to implement resource access control in OpenSearch.
  * This package will be added as a dependency by all OpenSearch plugins that require resource access control.
- *
- * @opensearch.experimental
  */
 package org.opensearch.security.spi.resources;

src/main/java/org/opensearch/security/resources/ResourceAccessControlClient.java

@@ -21,8 +21,6 @@
 /**
  * Access control client responsible for handling resource sharing operations such as verifying,
  * sharing, revoking, and listing access to shareable resources.
- *
- * @opensearch.experimental
  */
 public final class ResourceAccessControlClient implements ResourceSharingClient {
     private static final Logger LOGGER = LogManager.getLogger(ResourceAccessControlClient.class);
@@ -33,7 +31,6 @@ public final class ResourceAccessControlClient implements ResourceSharingClient
 
     /**
      * Constructs a new ResourceAccessControlClient.
-     *
      */
     public ResourceAccessControlClient(
         ResourceAccessHandler resourceAccessHandler,

src/main/java/org/opensearch/security/resources/ResourceAccessHandler.java

@@ -41,8 +41,6 @@
  * This class handles resource access permissions for users, roles and backend-roles.
  * It provides methods to check if a user has permission to access a resource
  * based on the resource sharing configuration.
- *
- * @opensearch.experimental
  */
 public class ResourceAccessHandler {
     private static final Logger LOGGER = LogManager.getLogger(ResourceAccessHandler.class);

src/main/java/org/opensearch/security/resources/ResourceIndexListener.java

@@ -30,8 +30,6 @@
 
 /**
  * This class implements an index operation listener for operations performed on resources stored in plugin's indices.
- *
- * @opensearch.experimental
  */
 public class ResourceIndexListener implements IndexingOperationListener {
 
@@ -80,7 +78,7 @@ public void postIndex(ShardId shardId, Engine.Index index, Engine.IndexResult re
         ResourceProvider provider = resourcePluginInfo.getResourceProvider(resourceType);
         if (provider == null) {
             log.warn(
-                "Failed to create a resource sharing entry for resource: {} with type: {}. The type is not declared as a protected type in plugins.security.experimental.resource_sharing.protected_types.",
+                "Failed to create a resource sharing entry for resource: {} with type: {}. The type is not declared as a protected type in plugins.security.resource_sharing.protected_types.",
                 resourceId,
                 resourceType
             );

src/main/java/org/opensearch/security/resources/ResourcePluginInfo.java

@@ -37,8 +37,6 @@
 /**
  * This class provides information about resource plugins and their associated resource providers and indices.
  * It follows the Singleton pattern to ensure that only one instance of the class exists.
- *
- * @opensearch.experimental
  */
 public class ResourcePluginInfo {
 

src/main/java/org/opensearch/security/resources/ResourceSharingIndexHandler.java

@@ -5,7 +5,6 @@
  * The OpenSearch Contributors require contributions made to
  * this file be licensed under the Apache-2.0 license or a
  * compatible open source license.
- *
  */
 package org.opensearch.security.resources;
 
@@ -84,8 +83,6 @@
 /**
  * This class handles the creation and management of the resource sharing index.
  * It provides methods to create the index, index resource sharing entries along with updates and deletion, retrieve shared resources.
- *
- * @opensearch.experimental
  */
 public class ResourceSharingIndexHandler {
 

src/main/java/org/opensearch/security/resources/sharing/CreatedBy.java

@@ -21,8 +21,6 @@
 
 /**
  * This class is used to store information about the creator of a resource.
- *
- * @opensearch.experimental
  */
 public class CreatedBy implements ToXContentFragment, NamedWriteable {
 

src/main/java/org/opensearch/security/resources/sharing/Recipient.java

@@ -11,8 +11,6 @@
 /**
  * Enum representing the recipients of a shared resource.
  * It includes USERS, ROLES, and BACKEND_ROLES.
- *
- * @opensearch.experimental
  */
 public enum Recipient {
     USERS("users"),

src/main/java/org/opensearch/security/resources/sharing/Recipients.java

@@ -33,8 +33,6 @@
  * "backend_roles": []
  * }
  * where "users", "roles" and "backend_roles" are the recipient entities, and "default" is the action-group
- *
- * @opensearch.experimental
  */
 public class Recipients implements ToXContentFragment, NamedWriteable {
 

src/main/java/org/opensearch/security/resources/sharing/ResourceSharing.java

@@ -39,7 +39,6 @@
  *   <li>The sharing permissions and recipients</li>
  * </ul>
  *
- * @opensearch.experimental
  * @see CreatedBy
  * @see ShareWith
  */

src/main/java/org/opensearch/security/resources/sharing/ShareWith.java

@@ -39,8 +39,6 @@
  *   }
  * }
  * </pre>
- *
- * @opensearch.experimental
  */
 
 public class ShareWith implements ToXContentFragment, NamedWriteable {

src/main/java/org/opensearch/security/support/ConfigConstants.java

@@ -430,13 +430,12 @@ public class ConfigConstants {
 
     public static final String OPENSEARCH_API_TOKENS_INDEX = ".opensearch_security_api_tokens";
     // Resource sharing feature-flag
-    public static final String OPENSEARCH_RESOURCE_SHARING_ENABLED = "plugins.security.experimental.resource_sharing.enabled";
+    public static final String OPENSEARCH_RESOURCE_SHARING_ENABLED = "plugins.security.resource_sharing.enabled";
     public static final boolean OPENSEARCH_RESOURCE_SHARING_ENABLED_DEFAULT = false;
 
     // Protected resource types
     // Resource sharing will only apply to these types
-    public static final String OPENSEARCH_RESOURCE_SHARING_PROTECTED_TYPES =
-        "plugins.security.experimental.resource_sharing.protected_types";
+    public static final String OPENSEARCH_RESOURCE_SHARING_PROTECTED_TYPES = "plugins.security.resource_sharing.protected_types";
     public static final List<String> OPENSEARCH_RESOURCE_SHARING_PROTECTED_TYPES_DEFAULT = List.of(); // defaults to no registered types as
                                                                                                       // protected
 

src/test/java/org/opensearch/security/resources/sharing/CreatedByTests.java

@@ -32,8 +32,6 @@
 
 /**
  * Test class for CreatedBy class
- *
- * @opensearch.experimental
  */
 public class CreatedByTests extends LuceneTestCase {
 

src/test/java/org/opensearch/security/resources/sharing/ShareWithTests.java

@@ -48,8 +48,6 @@
 
 /**
  * Test class for ShareWith class
- *
- * @opensearch.experimental
  */
 public class ShareWithTests extends LuceneTestCase {