[Yandex Cloud documentation](../../index.md) > [Yandex Managed Service for Trino](../index.md) > [Step-by-step guides](index.md) > Object access rules > Assigning rules for catalog session properties

# Assigning access rules for catalog session properties in Managed Service for Trino

Access rules for catalog session propertires define whether users can set certain catalog session properties in a Managed Service for Trino cluster.

{% note warning %}

Set rules for catalog session properties to limit user consumption of system resources.

{% endnote %}

For each user-property pair, the rules apply as follows:
* Rules are checked in the order of their declaration. The first rule matching the user-property pair applies.
* If none of the rules match the user-property pair, the user is not allowed to set that property.
* If no rules are specified for session properties, any user can set any session properties for all catalogs.
* Property access rules apply together with the top-level [rules for objects in catalogs](access-control-catalogs.md).

## Setting rules when creating a cluster {#set-at-create}

You can set access rules for catalog session properties when creating a Managed Service for Trino cluster.

{% note warning %}
  
Property names specified in the rules are not validated. If a property name contains an error, the rule will not apply correctly.
  
{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder where you want to create a Managed Service for Trino cluster.
  1. Navigate to **Managed Service for Trino**.
  1. Click **Create cluster** and set the cluster parameters.
  1. Under **Access settings**, click ![image](../../_assets/console-icons/chevron-down.svg).
  1. In the **Catalog session properties** field, click **Add rule**.
  1. In the window that opens, set up the rule:

     1. Optionally, provide a rule description in the **Comment** field.

     1. Optionally, in the **Users** field, select the users the rule applies to:
        1. Click **Add**.
        1. Select the users from the list that opens. Use the search bar above the list to find particular users.
        1. To deselect a user selected by mistake, click that user again in the list.
        
        If no user is selected, the rule applies to all users.

     1. Optionally, in the **Groups** field, select the user groups the rule applies to:
        1. Click **Add**.
        1. From the list that opens, select the groups. Use the search bar above the list to find particular groups.
        1. To delete a group selected by mistake, click it again in the list.
        
        If you select no groups, the rule applies to all user groups.

     1. In the **Allow** field, specify whether the user is allowed to set the property:
        * `No`: Not allowed.
        * `Yes`: Allowed.

     1. Optionally, specify the catalogs the rule applies to:
        * **Name**: Select catalog names. You can only select catalogs added in **Catalogs**.
        * **Name (regular expression)**: Enter a regular expression for catalog names.
        * **Not specified**: Rule applies to all catalogs in the cluster.

     1. Optionally, specify the properties the rule applies to:
        * **Name**: Select property names.
        * **Name (regular expression)**: Enter a regular expression. The rule applies to the properties whose names match the regular expression.
        * **Not specified**: The rule applies to all properties.

  1. Add other rules in the same way as needed.
  1. To delete a rule added by mistake, click ![trash-bin](../../_assets/console-icons/trash-bin.svg) in the line with this rule.
  1. Click **Create**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  To set access rules:

  1. Create a file named `access_control.yaml` and paste the following code into it:

     ```yaml
     catalog_session_properties:
       # Rule 1
       - allow: <permission_to_set_property>
         catalog:
           name_regexp: <regular_expression>
         property:
           names:
             any: [<list_of_property_names>]
           name_regexp: <regular_expression>
         groups: [<list_of_group_IDs>]
         users: [<list_of_user_IDs>]
         description: <rule_description>
       # Rule 2
       - <Rule_2_parameters>
       ...
       # Rule N
       - <Rule_N_parameters>
     ```

     Where:

     * `catalog_session_properties`: List of rules for catalog session properties. Each rule contains the required `allow` parameter, as well as the optional `catalog`, `property`, `groups`, `users`, and `description` parameters.

     * `allow`: Permission to set a property:
       * `YES`: User is allowed to set the property.
       * `NO`: User is not allowed to set the property.

     * `catalog`: Cluster catalogs the rule applies to. These are set using the `name_regexp` parameter (regular expression for catalog names). If the `catalog` section is not specified, the rule applies to all cluster catalogs.

     * `property`: Properties the rule applies to. If the `property` section is not specified, the rule applies to all properties.
       * `names`: List of property names.
       * `name_regexp`: Regular expression. The rule applies to the properties whose names match the regular expression.

       You can specify either `names` or `name_regexp` but not both.

     * The `users` and `groups` parameters define users the rule applies to.
     
       * `users`: List of user IDs. The rule will only apply to the specified users.
     
       * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
     
       You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
     
     * `description`: Rule description.

  1. View the description of the CLI command for creating a cluster:

     ```bash
     yc managed-trino cluster create --help
     ```

  1. Run this command:

     ```bash
     yc managed-trino cluster create \
       ...
       --access-control-from-file access_control.yaml
     ```

     For available cluster parameters and their descriptions, see [this guide](cluster-create.md#create-cluster).

- Terraform {#tf}

  1. Create a Terraform configuration file describing your [infrastructure](cluster-create.md).
  
  1. Add the `yandex_trino_access_control` resource with the `catalog_session_properties` rule list to the configuration file.
 
     ```hcl
     resource "yandex_trino_cluster" "<cluster_name>" {
       ...
     }

     resource "yandex_trino_catalog" "<catalog_1_name>" {
       ...
     }

     resource "yandex_trino_catalog" "<catalog_2_name>" {
       ...
     }

     ...

     resource "yandex_trino_catalog" "<catalog_N_name>" {
       ...
     }

     resource "yandex_trino_access_control" "trino_access_control" {
       ...
       cluster_id  = yandex_trino_cluster.<cluster_name>.id
       catalog_session_properties = [
         # Rule 1
         {
           allow         = "<permission_to_set_property>"
           catalog       = {
             ids         = [
               yandex_trino_catalog.<catalog_1_name>.id,
               yandex_trino_catalog.<catalog_2_name>.id,
               ... 
               yandex_trino_catalog.<catalog_N_name>.id
             ]
             name_regexp = "<regular_expression>"
           }
           property      = {
             names       = ["<list_of_property_names>"]
             name_regexp = "<regular_expression>"
           }
           users         = ["<list_of_user_IDs>"]
           groups        = ["<list_of_group_IDs>"]
           description   = "<rule_description>"
         },
         # Rule 2
         {
           ... 
         },
         ...
         # Rule N
         {
           ... 
         }
       ]
       ...
     }
     ```

     Where:

     * `catalog_session_properties`: List of rule sections for catalog session properties. Each rule contains the required `allow` parameter, as well as the optional `catalog`, `property`, `groups`, `users`, and `description` parameters.

     * `allow`: Permission to set a property:
       * `YES`: User is allowed to set the property.
       * `NO`: User is not allowed to set the property.

     * `catalog`: Cluster catalogs the rule applies to. If the `catalog` section is not specified, the rule applies to all cluster catalogs.
       * `ids`: List of catalog IDs. These catalogs must be created in the same manifest.
       * `name_regexp`: Regular expression. The rule applies to the catalogs whose names match the regular expression.

       You can specify either `ids` or `name_regexp` but not both.

     * `property`: Properties the rule applies to. If the `property` section is not specified, the rule applies to all properties.
       * `names`: List of property names.
       * `name_regexp`: Regular expression. The rule applies to the properties whose names match the regular expression.

       You can specify either `names` or `name_regexp` but not both.

     * The `users` and `groups` parameters define users the rule applies to.
     
       * `users`: List of user IDs. The rule will only apply to the specified users.
     
       * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
     
       You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
     
     * `description`: Rule description.

  1. Make sure the settings are correct.
  
      1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
      1. Run this command:
      
         ```bash
         terraform validate
         ```
      
         Terraform will show any errors found in your configuration files.
  
  1. Confirm resource changes.
  
      1. Run this command to view the planned changes:
      
         ```bash
         terraform plan
         ```
      
         If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
      
      1. If everything looks correct, apply the changes:
         1. Run this command:
      
            ```bash
            terraform apply
            ```
      
         1. Confirm updating the resources.
         1. Wait for the operation to complete.
 
  For more information, see [this Terraform provider guide](../../terraform/resources/trino_access_control.md).

- REST API {#api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```

  1. Create a file named `body.json` and paste the following code into it:

      ```json
      {
        <cluster_parameters>
        ...
        "trino": {
          "catalogs": [
            {
              "name": "catalog_1_name",
              ...
            },
            {
              "name": "catalog_2_name",
              ...
            },
            ...
            {
              "name": "catalog_N_name",
              ...
            }
          ]
          ...
          "accessControl": {
            "catalogSessionProperties": [
              {
                "allow": "<permission_to_set_property>",
                "catalog": {
                  "names": {
                    "any": [
                      "<catalog_1_name>",
                      "<catalog_2_name>",
                      ...
                      "<catalog_N_name>"
                    ]
                  },
                  "nameRegexp": "<regular_expression>"
                },
                "property": {
                  "names": {
                    "any": [
                      "<list_of_property_names>"
                    ]
                  },
                  "nameRegexp": "<regular_expression>"
                },
                "users": [
                  "<list_of_user_IDs>"
                ],
                "groups": [
                  "<list_of_group_IDs>"
                ],
                "description": "<rule_description>"
              },
              {
                <Rule_2_section>
              },
              ...
              {
                <Rule_N_section>
              }
            ]
          }
        }
      }
      ```

      Where:

      * `accessControl`: Access rule configuration in the cluster.

      * `catalogSessionProperties`: List of rule sections for catalog session properties. Each rule contains the required `allow` parameter, as well as the optional `catalog`, `property`, `groups`, `users`, and `description` parameters.

      * `allow`: Permission to set a property:
        * `YES`: User is allowed to set the property.
        * `NO`: User is not allowed to set the property.

      * `catalog`: Catalogs the rule applies to. If the `catalog` section is not specified, the rule applies to all cluster catalogs.
        * `names`: List of catalog names. You must create catalogs within the same [Cluster.Create](../api-ref/Cluster/create.md) call.
        * `nameRegexp`: Regular expression. The rule applies to the catalogs whose names match the regular expression.

        The `catalog` section must contain either the nested `names` section or the `nameRegexp` parameter.

      * `property`: Properties the rule applies to. If the `property` section is not specified, the rule applies to all properties.
        * `names`: List of property names.
        * `nameRegexp`: Regular expression. The rule applies to the properties whose names match the regular expression.

        The `property` section must contain either the nested `names` section or the `nameRegexp` parameter.

      * The `users` and `groups` parameters define users the rule applies to.
      
        * `users`: List of user IDs. The rule will only apply to the specified users.
      
        * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
      
        You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
      
      * `description`: Rule description.

      For available cluster parameters and their descriptions, see [this guide](cluster-create.md#create-cluster).

  1. Call the [Cluster.Create](../api-ref/Cluster/create.md) method, e.g., via the following [cURL](https://curl.se/) request:

      ```bash
      curl \
          --request POST \
          --header "Authorization: Bearer $IAM_TOKEN" \
          --url 'https://trino.api.cloud.yandex.net/managed-trino/v1/clusters'
          --data '@body.json'
      ```

  1. View the [server response](../api-ref/Cluster/create.md#yandex.cloud.operation.Operation) to make sure your request was successful.

- gRPC API {#grpc-api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and place it in an environment variable:

      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```

  1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Below, we assume that the repository contents reside in the `~/cloudapi/` directory.

  1. Create a file named `body.json` and paste the following code into it:

      ```json
      {
        <cluster_parameters>
        ...
        "trino": {
          "catalogs": [
            {
              "name": "catalog_1_name",
              ...
            },
            {
              "name": "catalog_2_name",
              ...
            },
            ...
            {
              "name": "catalog_N_name",
              ...
            }
          ]
          ...
          "access_control": {
            "catalog_session_properties": [
              {
                "allow": "<permission_to_set_property>",
                "catalog": {
                  "names": {
                    "any": [
                      "<catalog_1_name>",
                      "<catalog_2_name>",
                      ...
                      "<catalog_N_name>"
                    ]
                  },
                  "name_regexp": "<regular_expression>"
                },
                "property": {
                  "names": {
                    "any": [
                      "<list_of_property_names>"
                    ]
                  },
                  "name_regexp": "<regular_expression>"
                },
                "users": [
                  "<list_of_user_IDs>"
                ],
                "groups": [
                  "<list_of_group_IDs>"
                ],
                "description": "<rule_description>"
              },
              {
                <Rule_2_section>
              },
              ...
              {
                <Rule_N_section>
              }
            ]
          }
        }
      }
      ```

      Where:

      * `access_control`: Access rule configuration in the cluster.

      * `catalog_session_properties`: List of rule sections for catalog session properties. Each rule contains the required `allow` parameter, as well as the optional `catalog`, `property`, `groups`, `users`, and `description` parameters.

      * `allow`: Permission to set a property:
        * `YES`: User is allowed to set the property.
        * `NO`: User is not allowed to set the property.

      * `catalog`: Catalogs the rule applies to. If the `catalog` section is not specified, the rule applies to all cluster catalogs.
        * `names`: List of catalog names. You must create catalogs within the same [ClusterService/Create](../api-ref/grpc/Cluster/create.md) call.
        * `name_regexp`: Regular expression. The rule applies to the catalogs whose names match the regular expression.

        The `catalog` section must contain either the nested `names` section or the `name_regexp` parameter.

      * `property`: Properties the rule applies to. If the `property` section is not specified, the rule applies to all properties.
        * `names`: List of property names.
        * `name_regexp`: Regular expression. The rule applies to the properties whose names match the regular expression.

        The `property` section must contain either the nested `names` section or the `name_regexp` parameter.

      * The `users` and `groups` parameters define users the rule applies to.
      
        * `users`: List of user IDs. The rule will only apply to the specified users.
      
        * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
      
        You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
      
      * `description`: Rule description.

      For available cluster parameters and their descriptions, see [this guide](cluster-create.md#create-cluster).

  1. Call the [ClusterService/Create](../api-ref/grpc/Cluster/create.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

      ```bash
      grpcurl \
          -format json \
          -import-path ~/cloudapi/ \
          -import-path ~/cloudapi/third_party/googleapis/ \
          -proto ~/cloudapi/yandex/cloud/trino/v1/cluster_service.proto \
          -rpc-header "Authorization: Bearer $IAM_TOKEN" \
          -d @ \
          trino.api.cloud.yandex.net:443 \
          yandex.cloud.trino.v1.ClusterService.Create \
          < body.json
      ```

  1. Check the [server response](../api-ref/grpc/Cluster/create.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

## Setting rules for an existing cluster {#set-at-update}

You can set or update access rules for catalog session properties in an existing Managed Service for Trino cluster.

{% note warning %}
  
Property names specified in the rules are not validated. If a property name contains an error, the rule will not apply correctly.
  
{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), navigate to the relevant folder.
  1. Navigate to **Managed Service for&nbsp;Trino**.
  1. Click the cluster name.
  1. Go to **Access settings** → **Catalog session properties**.
  1. To add a rule, click **Add rule**. In the window that opens, set up the rule:

     1. Optionally, provide a rule description in the **Comment** field.

     1. Optionally, in the **Users** field, select the users the rule applies to:
        1. Click **Add**.
        1. Select the users from the list that opens. Use the search bar above the list to find particular users.
        1. To deselect a user selected by mistake, click that user again in the list.
        
        If no user is selected, the rule applies to all users.

     1. Optionally, in the **Groups** field, select the user groups the rule applies to:
        1. Click **Add**.
        1. From the list that opens, select the groups. Use the search bar above the list to find particular groups.
        1. To delete a group selected by mistake, click it again in the list.
        
        If you select no groups, the rule applies to all user groups.

     1. In the **Allow** field, specify whether the user is allowed to set the property:
        * `No`: Not allowed.
        * `Yes`: Allowed.

     1. Optionally, specify the catalogs the rule applies to:
        * **ID**: Select catalog IDs. You can only select catalogs from those present in the cluster.
        * **Name**: Select catalog names. You can only select catalogs added in **Catalogs**.
        * **Name (regular expression)**: Enter a regular expression for catalog names.
        * **Not specified**: Rule applies to all catalogs in the cluster.

     1. Optionally, specify the properties the rule applies to:
        * **Name**: Select property names.
        * **Name (regular expression)**: Enter a regular expression. The rule applies to the properties whose names match the regular expression.
        * **Not specified**: The rule applies to all properties.

     1. Optionally, in the **Session property** field, specify the properties the rule applies to:
        * **Name**: Select property names.
        * **Name (regular expression)**: Enter a regular expression. The rule applies to the properties whose names match the regular expression.
        * **Not specified**: The rule applies to all properties.

  1. Add other rules in the same way as needed.
  1. To edit a rule:
     1. Click ![trash-bin](../../_assets/console-icons/pencil.svg) in the line with this rule.
     1. Update the rule settings and click **Update**.
  1. To delete a rule you no longer need, Click ![trash-bin](../../_assets/console-icons/trash-bin.svg) in the line with this rule.
  1. Click **Save changes**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  To set access rules:

  1. If you have not set any access rules yet, create a file named `access_control.yaml` and paste the following into it:

     ```yaml
     catalog_session_properties:
       # Rule 1
       - allow: <permission_to_set_property>
         catalog:
           ids:
             any: [<list_of_catalog_IDs>]
           names:
             any: [<list_of_catalog_names>]
           name_regexp: <regular_expression>
         property:
           names:
             any: [<list_of_property_names>]
           name_regexp: <regular_expression>
         groups: [<list_of_group_IDs>]
         users: [<list_of_user_IDs>]
         description: <rule_description>
       # Rule 2
       - <Rule_2_parameters>
       ...
       # Rule N
       - <Rule_N_parameters>
     ```

     Where:

     * `system_session_properties`: List of rules for catalog session properties. Each rule contains the required `allow` parameter, as well as the optional `catalog`, `property`, `groups`, `users`, and `description` parameters.

     * `allow`: Permission to set a property:
       * `YES`: User is allowed to set the property.
       * `NO`: User is not allowed to set the property.

     * `catalog`: Catalogs the rule applies to. If the `catalog` section is not specified, the rule applies to all cluster catalogs.
       * `ids`: List of catalog IDs. These must be the existing catalogs.
       * `names`: List of catalog names. These must be the existing catalogs.
       * `name_regexp`: Regular expression. The rule applies to the catalogs whose names match the regular expression.

       You can specify only one of the following: `ids`, `names`, or `name_regexp`.

     * `property`: Properties the rule applies to. If the `property` section is not specified, the rule applies to all properties.
       * `names`: List of property names.
       * `name_regexp`: Regular expression. The rule applies to the properties whose names match the regular expression.

       You can specify either `names` or `name_regexp` but not both.

     * The `users` and `groups` parameters define users the rule applies to.
     
       * `users`: List of user IDs. The rule will only apply to the specified users.
     
       * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
     
       You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
     
     * `description`: Rule description.

  1. If you have already set the access rules, open `access_control.yaml` and edit it as needed. You can:

     * Add new rules.
     * Update the existing ones.
     * Delete the rules you no longer need.

  1. Run this command:

     ```bash
     yc managed-trino cluster set-access-control <cluster_name_or_ID> \
       --from-file access_control.yaml
     ```

     You can get the cluster ID and name with the [list of clusters in the folder](cluster-list.md#list-clusters).

- Terraform {#tf}

  1. Open the current Terraform configuration file with the infrastructure plan.
  
      To learn how to create this file, refer to [Creating a cluster](cluster-create.md).
  
  1. If you have not set any access rules yet, add the `yandex_trino_access_control` resource containing the `system_session_properties` rule list.

     ```hcl
     resource "yandex_trino_cluster" "<cluster_name>" {
       ...
     }

     resource "yandex_trino_catalog" "<catalog_1_name>" {
       ...
     }

     resource "yandex_trino_catalog" "<catalog_2_name>" {
       ...
     }

     ...

     resource "yandex_trino_catalog" "<catalog_N_name>" {
       ...
     }

     resource "yandex_trino_access_control" "trino_access_control" {
       ...
       cluster_id  = yandex_trino_cluster.<cluster_name>.id
       catalog_session_properties = [
         # Rule 1
         {
           allow         = "<permission_to_set_property>"
           catalog       = {
             ids         = [
               yandex_trino_catalog.<catalog_1_name>.id,
               yandex_trino_catalog.<catalog_2_name>.id,
               ... 
               yandex_trino_catalog.<catalog_N_name>.id
             ]
             name_regexp = "<regular_expression>"
           }
           property      = {
             names       = ["<list_of_property_names>"]
             name_regexp = "<regular_expression>"
           }
           users         = ["<list_of_user_IDs>"]
           groups        = ["<list_of_group_IDs>"]
           description   = "<rule_description>"
         },
         # Rule 2
         {
           ... 
         },
         ...
         # Rule N
         {
           ... 
         }
       ]
       ...
     }
     ```

     Where:

     * `catalog_session_properties`: List of rule sections for catalog session properties. Each rule contains the required `allow` parameter, as well as the optional `catalog`, `property`, `groups`, `users`, and `description` parameters.

     * `allow`: Permission to set a property:
       * `YES`: User is allowed to set the property.
       * `NO`: User is not allowed to set the property.

     * `catalog`: Cluster catalogs the rule applies to. If the `catalog` section is not specified, the rule applies to all cluster catalogs.
       * `ids`: List of catalog IDs. These must exist or be created in the same manifest.
       * `name_regexp`: Regular expression. The rule applies to the catalogs whose names match the regular expression.

       You can specify either `ids` or `name_regexp` but not both.

     * `property`: Properties the rule applies to. If the `property` section is not specified, the rule applies to all properties.
       * `names`: List of property names.
       * `name_regexp`: Regular expression. The rule applies to the properties whose names match the regular expression.

       You can specify either `names` or `name_regexp` but not both.

     * The `users` and `groups` parameters define users the rule applies to.
     
       * `users`: List of user IDs. The rule will only apply to the specified users.
     
       * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
     
       You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
     
     * `description`: Rule description.

  1. If you have already set the access rules, edit the `yandex_trino_access_control` resource description. You can:

     * Add new rules.
     * Update the existing ones.
     * Delete the rules you no longer need.

  1. Make sure the settings are correct.
  
      1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
      1. Run this command:
      
         ```bash
         terraform validate
         ```
      
         Terraform will show any errors found in your configuration files.
  
  1. Confirm resource changes.
  
      1. Run this command to view the planned changes:
      
         ```bash
         terraform plan
         ```
      
         If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
      
      1. If everything looks correct, apply the changes:
         1. Run this command:
      
            ```bash
            terraform apply
            ```
      
         1. Confirm updating the resources.
         1. Wait for the operation to complete.
 
  For more information, see [this Terraform provider guide](../../terraform/resources/trino_access_control.md).

- REST API {#api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```

  1. If you have not set any access rules yet, create a file named `body.json` and paste the following code into it:

      ```json
      {
        "updateMask": "trino.accessControl.systemSessionProperties",
        "trino": {
          "accessControl": {
            "systemSessionProperties": [
              {
                "allow": "<permission_to_set_property>",
                "catalog": {
                  "ids": {
                    "any": [
                      "<list_of_catalog_IDs>"
                    ]
                  },
                  "names": {
                    "any": [
                      "<list_of_catalog_names>"
                    ]
                  },
                  "nameRegexp": "<regular_expression>"
                },
                "property": {
                  "names": {
                    "any": [
                      "<list_of_property_names>"
                    ]
                  },
                  "nameRegexp": "<regular_expression>"
                },
                "users": [
                  "<list_of_user_IDs>"
                ],
                "groups": [
                  "<list_of_group_IDs>"
                ],
                "description": "<rule_description>"
              },
              {
                <Rule_2_section>
              },
              ...
              {
                <Rule_N_section>
              }
            ]
          }
        }
      }
      ```

      Where:

      * `updateMask`: Comma-separated list of parameters to update.

          {% note warning %}

          When you update a cluster, all parameters of the object you are modifying will be reset to their defaults unless explicitly provided in the request. To avoid this, list the settings you want to change in the `updateMask` parameter.

          {% endnote %}

      * `accessControl`: Access rule configuration in the cluster.

      * `systemSessionProperties`: List of rule sections for session system properties. Each rule contains the required `allow` parameter, as well as the optional `property`, `groups`, `users`, and `description` parameters.

      * `allow`: Permission to set a property:
        * `YES`: User is allowed to set the property.
        * `NO`: User is not allowed to set the property.

      * `catalog`: Catalogs the rule applies to. If the `catalog` section is not specified, the rule applies to all cluster catalogs.
        * `ids`: List of catalog IDs. These must be the existing catalogs.
        * `names`: List of catalog names. These must be the existing catalogs.
        * `nameRegexp`: Regular expression. The rule applies to the catalogs whose names match the regular expression.

        The `catalog` section must contain either one of the nested `ids` or `names` sections, or the `name_regexp` parameter.

      * `property`: Properties the rule applies to. If the `property` section is not specified, the rule applies to all properties.
        * `names`: List of property names.
        * `nameRegexp`: Regular expression. The rule applies to the properties whose names match the regular expression.

        The `property` section must contain either the nested `names` section or the `nameRegexp` parameter.

      * The `users` and `groups` parameters define users the rule applies to.
      
        * `users`: List of user IDs. The rule will only apply to the specified users.
      
        * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
      
        You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
      
      * `description`: Rule description.

  1. If you have already set the access rules, open the existing `body.json` rules file and edit it as needed. You can:

     * Add new rules.
     * Update the existing ones.
     * Delete the rules you no longer need.

  1. Call the [Cluster.Update](../api-ref/Cluster/update.md) method, e.g., via the following [cURL](https://curl.se/) request:

      ```bash
      curl \
        --request PATCH \
        --header "Authorization: Bearer $IAM_TOKEN" \
        --url 'https://trino.api.cloud.yandex.net/managed-trino/v1/clusters/<cluster_ID>'
        --data '@body.json'
      ```

      You can get the cluster ID with the [list of clusters](cluster-list.md#list-clusters) in the folder.

  1. Check the [server response](../api-ref/Cluster/update.md#yandex.cloud.operation.Operation) to make sure your request was successful.

- gRPC API {#grpc-api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```

  1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Below, we assume that the repository contents reside in the `~/cloudapi/` directory.

  1. If you have not set any access rules yet, create a file named `body.json` and paste the following code into it:

      ```json
      {
        "cluster_id": "<cluster_ID>",
        "update_mask": {
          "paths": [
            "trino.access_control.catalog_session_properties"
          ]
        },
        "trino": {
          "access_control": {
            "catalog_session_properties": [
              {
                "allow": "<permission_to_set_property>",
                "catalog": {
                  "ids": {
                    "any": [
                      "<list_of_catalog_IDs>"
                    ]
                  },
                  "names": {
                    "any": [
                      "<list_of_catalog_names>"
                    ]
                  },
                  "name_regexp": "<regular_expression>"
                },
                "property": {
                  "names": {
                    "any": [
                      "<list_of_property_names>"
                    ]
                  },
                  "name_regexp": "<regular_expression>"
                },
                "users": [
                  "<list_of_user_IDs>"
                ],
                "groups": [
                  "<list_of_group_IDs>"
                ],
                "description": "<rule_description>"
              },
              {
                <Rule_2_section>
              },
              ...
              {
                <Rule_N_section>
              }
            ]
          }
        }
      }
      ```

      Where:

      * `cluster_id`: Cluster ID.
          
          You can get the cluster ID with the [list of clusters](cluster-list.md#list-clusters) in the folder.

      * `update_mask`: List of parameters to update as an array of strings (`paths[]`).

          {% cut "Format for listing settings" %}

          ```yaml
          "update_mask": {
            "paths": [
              "<setting_1>",
              "<setting_2>",
              ...
              "<setting_N>"
            ]
          }
          ```

          {% endcut %}

          {% note warning %}

          When you update a cluster, all parameters of the object you are modifying will be reset to their defaults unless explicitly provided in the request. To avoid this, list the settings you want to change in the `update_mask` parameter.

          {% endnote %}

      * `access_control`: Access rule configuration in the cluster.

      * `system_session_properties`: List of rule sections for catalog session properties. Each rule contains the required `allow` parameter, as well as the optional `catalog`, `property`, `groups`, `users`, and `description` parameters.

      * `allow`: Permission to set a property:
        * `YES`: User is allowed to set the property.
        * `NO`: User is not allowed to set the property.

      * `catalog`: Catalogs the rule applies to. If the `catalog` section is not specified, the rule applies to all cluster catalogs.
        * `ids`: List of catalog IDs. These must be the existing catalogs.
        * `names`: List of catalog names. These must be the existing catalogs.
        * `name_regexp`: Regular expression. The rule applies to the catalogs whose names match the regular expression.

        The `catalog` section must contain either one of the nested `ids` or `names` sections, or the `name_regexp` parameter.

      * `property`: Properties the rule applies to. If the `property` section is not specified, the rule applies to all properties.
        * `names`: List of property names.
        * `name_regexp`: Regular expression. The rule applies to the properties whose names match the regular expression.

        The `property` section must contain either the nested `names` section or the `name_regexp` parameter.

      * The `users` and `groups` parameters define users the rule applies to.
      
        * `users`: List of user IDs. The rule will only apply to the specified users.
      
        * `groups`: List of group IDs. The rule will only apply to users who belong to at least one of these groups.
      
        You can specify either one or both parameters. If you specify both, the rule will apply to all users from the `users` parameter who also belong to at least one group listed under `groups`. If neither parameter is provided, the rule will apply to all users.
      
      * `description`: Rule description.

  1. If you have already set the access rules, open the existing `body.json` rules file and edit it as needed. You can:

     * Add new rules.
     * Update the existing ones.
     * Delete the rules you no longer need.

  1. Call the [ClusterService.Update](../api-ref/grpc/Cluster/update.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

      ```bash
      grpcurl \
        -format json \
        -import-path ~/cloudapi/ \
        -import-path ~/cloudapi/third_party/googleapis/ \
        -proto ~/cloudapi/yandex/cloud/trino/v1/cluster_service.proto \
        -rpc-header "Authorization: Bearer $IAM_TOKEN" \
        -d @ \
        trino.api.cloud.yandex.net:443 \
        yandex.cloud.trino.v1.ClusterService.Update \
        < body.json
      ```

  1. Check the [server response](../api-ref/grpc/Cluster/update.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

## Example of setting access rules for catalog session properties {#example}

Let's configure access rules for catalog session properties:
1. Allow users in the group with the `admins_group_id` to set any properties.
1. Allow users in the group with the `analytics_group_id` to set properties with names such as `parquet_.*` in the catalog with the `hive_cat_id`.
1. Prohibit all other users from setting properties.

{% list tabs group=instructions %}

- CLI {#cli}

  The `access_control.yaml` file for this rule set is as follows:

  ```yaml
  catalog_session_properties:
    - groups: 
        - admins_group_id
      allow: YES

    - groups: 
        - data_engineers_group_id
      property:
        name_regexp: "parquet.*"
      catalog:
        ids:
          any:
            - hive_cat_id
      allow: YES
  ```

- Terraform {#tf}

  The configuration file for this rule set is as follows:

  ```hcl
  resource "yandex_trino_access_control" "trino_access_control" {
    ...
    cluster_id  = <cluster_ID>
    catalog_session_properties = [
      {
        groups        = ["admins_group_id"]
        allow         = "YES"
      },
      {
        groups        = ["data_engineers_group_id"]
        property      = {
          name_regexp = "parquet.*"
        }
        catalog       = {
          ids         = ["hive_cat_id"]
        }
        allow         = "YES"
      }
    ]
    ...
  }
  ```

- REST API {#api}

  The `body.json` file for this rule set is as follows:

  ```json
  {
    "updateMask": "trino.accessControl.systemSessionProperties",
    "trino": {
      "accessControl": {
        "systemSessionProperties": [
          {
            "groups": [
              "admins_group_id"
            ],
            "allow": "YES"
          },
          {
            "groups": [
              "data_engineers_group_id"
            ],
            "catalog": {
              "ids": {
                "any": ["hive_cat_id"]
              }
            },
            "property": {
              "nameRegexp": "parquet.*"
            },
            "allow": "YES"
          }
        ]
      }
    }
  }
  ```

- gRPC API {#grpc-api}

  The `body.json` file for this rule set is as follows:

  ```json
  {
    "cluster_id": "<cluster_ID>",
    "update_mask": {
      "paths": [
        "trino.access_control.catalog_session_properties"
      ]
    },
    "trino": {
      "access_control": {
        "catalog_session_properties": [
          {
            "groups": [
              "admins_group_id"
            ],
            "allow": "YES"
          },
          {
            "groups": [
              "data_engineers_group_id"
            ],
            "catalog": {
              "ids": {
                "any": ["hive_cat_id"]
              }
            },
            "property": {
              "name_regexp": "parquet.*"
            },
            "allow": "YES"
          }
        ]
      }
    }
  }
  ```

{% endlist %}