You're viewing version 2.13 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Register a model group

To register a model group, send a POST request to the _register endpoint. You can register a model group in public, private, or restricted access mode.

Each model group name in the cluster must be globally unique.

For more information, see Model access control.

Path and HTTP method

POST /_plugins/_ml/model_groups/_register

Request fields

The following table lists the available request fields.

Example request

POST /_plugins/_ml/model_groups/_register
{
    "name": "test_model_group_public",
    "description": "This is a public model group",
    "access_mode": "public"
}

Example response

{
    "model_group_id": "GDNmQ4gBYW0Qyy5ZcBcg",
    "status": "CREATED"
}

Response fields

The following table lists the available response fields.

Registering a public model group

If you register a model group with a public access mode, any model in this model group will be accessible to any user with access to the cluster. The following request registers a public model group:

POST /_plugins/_ml/model_groups/_register
{
    "name": "test_model_group_public",
    "description": "This is a public model group",
    "access_mode": "public"
}

Registering a restricted model group

To limit access by backend role, you must register a model group with the restricted access mode.

When registering a model group, you must attach one or more of your backend roles to the model using one but not both of the following methods: - Provide a list of backend roles in the backend_roles parameter. - Set the add_all_backend_roles parameter to true to add all your backend roles to the model group. This option is not available to admin users.

Any user who shares a backend role with the model group can access any model in this model group. This grants the user the permissions included with the user role that is mapped to the backend role.

An admin user can access all model groups regardless of their access mode.

Example request: A list of backend roles

The following request registers a restricted model group, which can be accessed only by users with the IT backend role:

POST /_plugins/_ml/model_groups/_register
{
    "name": "model_group_test",
    "description": "This is an example description",
    "access_mode": "restricted",
    "backend_roles" : ["IT"]
}

Example request: All backend roles

The following request registers a restricted model group, adding all backend roles of the user to the model group:

POST /_plugins/_ml/model_groups/_register
{
    "name": "model_group_test",
    "description": "This is an example description",
    "access_mode": "restricted",
    "add_all_backend_roles": "true"
}

Registering a private model group

If you register a model group with a private access mode, any model in this model group will be accessible only to you and the admin users. The following request registers a private model group:

POST /_plugins/_ml/model_groups/_register
{
    "name": "model_group_test",
    "description": "This is an example description",
    "access_mode": "private"
}

If you don’t specify any of the access_mode, backend_roles, or add_all_backend_roles, the model will have a private access mode:

POST /_plugins/_ml/model_groups/_register
{
    "name": "model_group_test",
    "description": "This is an example description"
}

Registering a model group in a cluster where model access control is disabled

If model access control is disabled on your cluster (one of the prerequisites is not met), you can register a model group with a name and description but cannot specify any of the access parameters (model_access_name, backend_roles, or add_backend_roles). By default, in such a cluster, all model groups are public.