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.
Field | Data type | Description |
---|---|---|
name | String | The model group name. Required. |
description | String | The model group description. Optional. |
access_mode | String | The access mode for this model. Valid values are public , private , and restricted . When this parameter is set to restricted , you must specify either backend_roles or add_all_backend_roles , but not both. Optional. If you specify none of the security parameters (access_mode , backend_roles , and add_all_backend_roles ), the default access_mode is private . |
backend_roles | Array | A list of the model owner’s backend roles to add to the model. Can be specified only if access_mode is restricted . Cannot be specified at the same time as add_all_backend_roles . Optional. |
add_all_backend_roles | Boolean | If true , all backend roles of the model owner are added to the model group. Default is false . Cannot be specified at the same time as backend_roles . Admin users cannot set this parameter to true . Optional. |
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.
Field | Data type | Description |
---|---|---|
model_group_id | String | The model group ID that you can use to access this model group. |
status | String | The operation status. |
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.