[Документация Yandex Cloud](../../index.md) > [Yandex Managed Service for Trino](../index.md) > [Пошаговые инструкции](index.md) > Правила доступа к объектам > Назначение правил для свойств сессии каталога

# Назначение правил доступа к свойствам сессии каталога в Managed Service for Trino

Правила доступа к свойствам сессии каталога определяют, могут ли пользователи устанавливать те или иные свойства сессии каталога в кластере Managed Service for Trino.

{% note warning %}

Установите правила для свойств сессии каталога, чтобы избежать злоупотребления системными ресурсами со стороны пользователей.

{% endnote %}

Для каждой пары пользователь-свойство правила применяются следующим образом:
* Правила проверяются в порядке их объявления. Применяется первое найденное правило, которое соответствует паре пользователь-свойство.
* Если ни одно из заданных правил не соответствует паре пользователь-свойство, пользователю запрещается устанавливать это свойство.
* Если для свойств сессии не задано ни одно правило, каждый пользователь может устанавливать любые свойства сессии для всех каталогов.
* Правила доступа к свойствам применяются совместно с общими [правилами доступа к объектам каталогов](access-control-catalogs.md).

## Назначить правила при создании кластера {#set-at-create}

Правила доступа к свойствам сессии каталога можно назначить одновременно с созданием кластера Managed Service for Trino.

{% note warning %}
  
Указанные в правилах имена свойств не проверяются на валидность. Ошибка в имени свойства приведет к некорректной работе правила.
  
{% endnote %}

{% list tabs group=instructions %}

- Консоль управления {#console}

  1. В [консоли управления](https://kz.console.yandex.cloud) выберите каталог, в котором нужно создать кластер Managed Service for Trino.
  1. Перейдите в сервис **Managed Service for Trino**.
  1. Нажмите кнопку **Создать кластер** и задайте параметры кластера.
  1. В блоке **Настройки доступа** нажмите на значок ![image](../../_assets/console-icons/chevron-down.svg).
  1. В поле **Свойства сессии каталога** нажмите кнопку **Добавить правило**.
  1. В открывшемся окне задайте параметры правила:

     1. (Опционально) В поле **Комментарий** введите описание правила.

     1. (Опционально) В поле **Пользователи** выберите пользователей, на которых распространяется правило:
        1. Нажмите кнопку **Добавить**.
        1. В открывшемся списке выберите нужных пользователей. Чтобы найти пользователя, используйте строку поиска над списком.
        1. Чтобы удалить пользователя, выбранного по ошибке, повторно нажмите на него в списке.
        
        Если не выбран ни один пользователь, правило распространяется на всех пользователей.

     1. (Опционально) В поле **Группы** выберите группы пользователей, на которые распространяется правило:
        1. Нажмите кнопку **Добавить**.
        1. В открывшемся списке выберите нужные группы. Чтобы найти группу, используйте строку поиска над списком.
        1. Чтобы удалить группу, выбранную по ошибке, повторно нажмите на нее в списке.
        
        Если не выбрана ни одна группа, правило распространяется на все группы пользователей.

     1. В поле **Allow** укажите, разрешено ли пользователю устанавливать свойство:
        * `No` — запрещено,
        * `Yes` — разрешено.

     1. (Опционально) Укажите, на какие каталоги распространяется правило:
        * **Имя** — выберите имена каталогов. Можно выбрать только каталоги, добавленные в блоке **Каталоги**.
        * **Имя (регулярное выражение)** — введите регулярное выражение для имен каталогов.
        * **Не задано** — правило распространяется на все каталоги кластера.

     1. (Опционально) Укажите, на какие свойства распространяется правило:
        * **Имя** — выберите имена свойств.
        * **Имя (регулярное выражение)** — введите регулярное выражение. Правило распространяется на свойства, имена которых соответствуют регулярному выражению.
        * **Не задано** — правило распространяется на все свойства.

  1. При необходимости добавьте другие правила аналогичным образом.
  1. Чтобы удалить правило, добавленное по ошибке, в строке этого правила нажмите на значок ![trash-bin](../../_assets/console-icons/trash-bin.svg).
  1. Нажмите кнопку **Создать**.

- CLI {#cli}

  Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), [установите и инициализируйте его](../../cli/quickstart.md#install).

  По умолчанию используется каталог, указанный при [создании](../../cli/operations/profile/profile-create.md) профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду `yc config set folder-id <идентификатор_каталога>`. Также для любой команды вы можете указать другой каталог с помощью параметров `--folder-name` или `--folder-id`. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа.

  Чтобы задать правила доступа:

  1. Создайте файл `access_control.yaml` и добавьте в него следующее содержимое:

     ```yaml
     catalog_session_properties:
       # Правило 1
       - allow: <право_установить_свойство>
         catalog:
           name_regexp: <регулярное_выражение>
         property:
           names:
             any: [<список_имен_свойств>]
           name_regexp: <регулярное_выражение>
         groups: [<список_идентификаторов_групп>]
         users: [<список_идентификаторов_пользователей>]
         description: <описание_правила>
       # Правило 2
       - <Параметры_правила_2>
       ...
       # Правило N
       - <Параметры_правила_N>
     ```

     Где:

     * `catalog_session_properties` — список правил для свойств сессии каталога. Каждое правило включает в себя обязательный параметр `allow`, а также опциональные параметры: `catalog`, `property`, `groups`, `users` и `description`.

     * `allow` — право установить свойство:
       * `YES` — пользователю разрешено установить свойство.
       * `NO` — пользователю запрещено установить свойство.

     * `catalog` — каталоги кластера, на которые распространяется правило. Задаются с помощью параметра `name_regexp` (регулярное выражение для имен каталогов). Если блок `catalog` не указан, правило распространяется на все каталоги кластера.

     * `property` — свойства, на которые распространяется правило. Если блок `property` не указан, правило распространяется на все свойства.
       * `names` — список имен свойств.
       * `name_regexp` — регулярное выражение. Правило распространяется на свойства, имена которых соответствуют регулярному выражению.

       Вы можете указать только один из параметров: `names` или `name_regexp`.

     * Параметры `users` и `groups` определяют пользователей, к которым применяется правило:
     
       * `users` — список идентификаторов пользователей. Правило применяется только к перечисленным пользователям.
     
       * `groups` — список идентификаторов групп. Правило применяется только к пользователям, которые входят хотя бы в одну из перечисленных групп.
     
       Вы можете указать один из параметров или оба. Если указаны оба параметра, правило применяется к каждому пользователю из параметра `users`, входящему хотя бы в одну группу из параметра `groups`. Если оба параметра не указаны, правило применяется ко всем пользователям.
     
     * `description` — описание правила.

  1. Посмотрите описание команды CLI для создания кластера:

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

  1. Выполните команду:

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

     Доступные параметры кластера и их описания представлены в [инструкции](cluster-create.md#create-cluster).

- Terraform {#tf}

  1. Создайте конфигурационный файл Terraform с [планом инфраструктуры](cluster-create.md).
  
  1. Добавьте в конфигурационный файл ресурс `yandex_trino_access_control`, содержащий список правил `catalog_session_properties`.
 
     ```hcl
     resource "yandex_trino_cluster" "<имя_кластера>" {
       ...
     }

     resource "yandex_trino_catalog" "<имя_каталога_1>" {
       ...
     }

     resource "yandex_trino_catalog" "<имя_каталога_2>" {
       ...
     }

     ...

     resource "yandex_trino_catalog" "<имя_каталога_N>" {
       ...
     }

     resource "yandex_trino_access_control" "trino_access_control" {
       ...
       cluster_id  = yandex_trino_cluster.<имя_кластера>.id
       catalog_session_properties = [
         # Правило 1
         {
           allow         = "<право_установить_свойство>"
           catalog       = {
             ids         = [
               yandex_trino_catalog.<имя_каталога_1>.id,
               yandex_trino_catalog.<имя_каталога_2>.id,
               ... 
               yandex_trino_catalog.<имя_каталога_N>.id
             ]
             name_regexp = "<регулярное_выражение>"
           }
           property      = {
             names       = ["<список_имен_свойств>"]
             name_regexp = "<регулярное_выражение>"
           }
           users         = ["<список_идентификаторов_пользователей>"]
           groups        = ["<список_идентификаторов_групп>"]
           description   = "<описание_правила>"
         },
         # Правило 2
         {
           ... 
         },
         ...
         # Правило N
         {
           ... 
         }
       ]
       ...
     }
     ```

     Где:

     * `catalog_session_properties` — список блоков правил для свойств сессии каталога. Каждое правило включает в себя обязательный параметр `allow`, а также опциональные параметры: `catalog`, `property`, `groups`, `users` и `description`.

     * `allow` — право установить свойство:
       * `YES` — пользователю разрешено установить свойство.
       * `NO` — пользователю запрещено установить свойство.

     * `catalog` — каталоги кластера, на которые распространяется правило. Если блок `catalog` не указан, правило распространяется на все каталоги кластера.
       * `ids` — список идентификаторов каталогов. Указанные каталоги должны создаваться в том же манифесте.
       * `name_regexp` — регулярное выражение. Правило распространяется на каталоги, имена которых соответствуют регулярному выражению.

       Вы можете указать только один из параметров: `ids` или `name_regexp`.

     * `property` — свойства, на которые распространяется правило. Если блок `property` не указан, правило распространяется на все свойства.
       * `names` — список имен свойств.
       * `name_regexp` — регулярное выражение. Правило распространяется на свойства, имена которых соответствуют регулярному выражению.

       Вы можете указать только один из параметров: `names` или `name_regexp`.

     * Параметры `users` и `groups` определяют пользователей, к которым применяется правило:
     
       * `users` — список идентификаторов пользователей. Правило применяется только к перечисленным пользователям.
     
       * `groups` — список идентификаторов групп. Правило применяется только к пользователям, которые входят хотя бы в одну из перечисленных групп.
     
       Вы можете указать один из параметров или оба. Если указаны оба параметра, правило применяется к каждому пользователю из параметра `users`, входящему хотя бы в одну группу из параметра `groups`. Если оба параметра не указаны, правило применяется ко всем пользователям.
     
     * `description` — описание правила.

  1. Проверьте корректность настроек.
  
      1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.
      1. Выполните команду:
      
         ```bash
         terraform validate
         ```
      
         Если в файлах конфигурации есть ошибки, Terraform на них укажет.
  
  1. Подтвердите изменение ресурсов.
  
      1. Выполните команду для просмотра планируемых изменений:
      
         ```bash
         terraform plan
         ```
      
         Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.
      
      1. Если вас устраивают планируемые изменения, внесите их:
         1. Выполните команду:
      
            ```bash
            terraform apply
            ```
      
         1. Подтвердите изменение ресурсов.
         1. Дождитесь завершения операции.
 
  Подробнее в [документации провайдера Terraform](../../terraform/resources/trino_access_control.md).

- REST API {#api}

  1. [Получите IAM-токен для аутентификации в API](../api-ref/authentication.md) и поместите токен в переменную среды окружения:

      ```bash
      export IAM_TOKEN="<IAM-токен>"
      ```

  1. Создайте файл `body.json` и добавьте в него следующее содержимое:

      ```json
      {
        <Параметры_кластера>
        ...
        "trino": {
          "catalogs": [
            {
              "name": "имя_каталога_1",
              ...
            },
            {
              "name": "имя_каталога_2",
              ...
            },
            ...
            {
              "name": "имя_каталога_N",
              ...
            }
          ]
          ...
          "accessControl": {
            "catalogSessionProperties": [
              {
                "allow": "<право_установить_свойство>",
                "catalog": {
                  "names": {
                    "any": [
                      "<имя_каталога_1>",
                      "<имя_каталога_2>",
                      ...
                      "<имя_каталога_N>"
                    ]
                  },
                  "nameRegexp": "<регулярное_выражение>"
                },
                "property": {
                  "names": {
                    "any": [
                      "<список_имен_свойств>"
                    ]
                  },
                  "nameRegexp": "<регулярное_выражение>"
                },
                "users": [
                  "<список_идентификаторов_пользователей>"
                ],
                "groups": [
                  "<список_идентификаторов_групп>"
                ],
                "description": "<описание_правила>"
              },
              {
                <Блок_правила_2>
              },
              ...
              {
                <Блок_правила_N>
              }
            ]
          }
        }
      }
      ```

      Где:

      * `accessControl` — конфигурация прав доступа в рамках кластера.

      * `catalogSessionProperties` — список блоков правил для свойств сессии каталога. Каждое правило включает в себя обязательный параметр `allow`, а также опциональные параметры: `catalog`, `property`, `groups`, `users` и `description`.

      * `allow` — право установить свойство:
        * `YES` — пользователю разрешено установить свойство.
        * `NO` — пользователю запрещено установить свойство.

      * `catalog` — каталоги, на которые распространяется правило. Если блок `catalog` не указан, правило распространяется на все каталоги кластера.
        * `names` — список имен каталогов. Каталоги должны создаваться в этом же вызове [Cluster.Create](../api-ref/Cluster/create.md).
        * `nameRegexp` — регулярное выражение. Правило распространяется на каталоги, имена которых соответствуют регулярному выражению.

        Блок `catalog` должен содержать либо вложенный блок `names`, либо параметр `nameRegexp`.

      * `property` — свойства, на которые распространяется правило. Если блок `property` не указан, правило распространяется на все свойства.
        * `names` — список имен свойств.
        * `nameRegexp` — регулярное выражение. Правило распространяется на свойства, имена которых соответствуют регулярному выражению.

        Блок `property` должен содержать либо вложенный блок `names`, либо параметр `nameRegexp`.

      * Параметры `users` и `groups` определяют пользователей, к которым применяется правило:
      
        * `users` — список идентификаторов пользователей. Правило применяется только к перечисленным пользователям.
      
        * `groups` — список идентификаторов групп. Правило применяется только к пользователям, которые входят хотя бы в одну из перечисленных групп.
      
        Вы можете указать один из параметров или оба. Если указаны оба параметра, правило применяется к каждому пользователю из параметра `users`, входящему хотя бы в одну группу из параметра `groups`. Если оба параметра не указаны, правило применяется ко всем пользователям.
      
      * `description` — описание правила.

      Доступные параметры кластера и их описания представлены в [инструкции](cluster-create.md#create-cluster).

  1. Воспользуйтесь методом [Cluster.Create](../api-ref/Cluster/create.md) и выполните запрос, например с помощью [cURL](https://curl.se/):

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

  1. Убедитесь, что запрос был выполнен успешно, изучив [ответ сервера](../api-ref/Cluster/create.md#yandex.cloud.operation.Operation).

- gRPC API {#grpc-api}

  1. [Получите IAM-токен для аутентификации в API](../api-ref/authentication.md) и поместите токен в переменную среды окружения:

      ```bash
      export IAM_TOKEN="<IAM-токен>"
      ```

  1. Клонируйте репозиторий [cloudapi](https://github.com/yandex-cloud/cloudapi):
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Далее предполагается, что содержимое репозитория находится в директории `~/cloudapi/`.

  1. Создайте файл `body.json` и добавьте в него следующее содержимое:

      ```json
      {
        <Параметры_кластера>
        ...
        "trino": {
          "catalogs": [
            {
              "name": "имя_каталога_1",
              ...
            },
            {
              "name": "имя_каталога_2",
              ...
            },
            ...
            {
              "name": "имя_каталога_N",
              ...
            }
          ]
          ...
          "access_control": {
            "catalog_session_properties": [
              {
                "allow": "<право_установить_свойство>",
                "catalog": {
                  "names": {
                    "any": [
                      "<имя_каталога_1>",
                      "<имя_каталога_2>",
                      ...
                      "<имя_каталога_N>"
                    ]
                  },
                  "name_regexp": "<регулярное_выражение>"
                },
                "property": {
                  "names": {
                    "any": [
                      "<список_имен_свойств>"
                    ]
                  },
                  "name_regexp": "<регулярное_выражение>"
                },
                "users": [
                  "<список_идентификаторов_пользователей>"
                ],
                "groups": [
                  "<список_идентификаторов_групп>"
                ],
                "description": "<описание_правила>"
              },
              {
                <Блок_правила_2>
              },
              ...
              {
                <Блок_правила_N>
              }
            ]
          }
        }
      }
      ```

      Где:

      * `access_control` — конфигурация прав доступа в рамках кластера.

      * `catalog_session_properties` — список блоков правил для свойств сессии каталога. Каждое правило включает в себя обязательный параметр `allow`, а также опциональные параметры: `catalog`, `property`, `groups`, `users` и `description`.

      * `allow` — право установить свойство:
        * `YES` — пользователю разрешено установить свойство.
        * `NO` — пользователю запрещено установить свойство.

      * `catalog` — каталоги, на которые распространяется правило. Если блок `catalog` не указан, правило распространяется на все каталоги кластера.
        * `names` — список имен каталогов. Каталоги должны создаваться в этом же вызове [ClusterService/Create](../api-ref/grpc/Cluster/create.md).
        * `name_regexp` — регулярное выражение. Правило распространяется на каталоги, имена которых соответствуют регулярному выражению.

        Блок `catalog` должен содержать либо вложенный блок `names`, либо параметр `name_regexp`.

      * `property` — свойства, на которые распространяется правило. Если блок `property` не указан, правило распространяется на все свойства.
        * `names` — список имен свойств.
        * `name_regexp` — регулярное выражение. Правило распространяется на свойства, имена которых соответствуют регулярному выражению.

        Блок `property` должен содержать либо вложенный блок `names`, либо параметр `name_regexp`.

      * Параметры `users` и `groups` определяют пользователей, к которым применяется правило:
      
        * `users` — список идентификаторов пользователей. Правило применяется только к перечисленным пользователям.
      
        * `groups` — список идентификаторов групп. Правило применяется только к пользователям, которые входят хотя бы в одну из перечисленных групп.
      
        Вы можете указать один из параметров или оба. Если указаны оба параметра, правило применяется к каждому пользователю из параметра `users`, входящему хотя бы в одну группу из параметра `groups`. Если оба параметра не указаны, правило применяется ко всем пользователям.
      
      * `description` — описание правила.

      Доступные параметры кластера и их описания представлены в [инструкции](cluster-create.md#create-cluster).

  1. Воспользуйтесь вызовом [ClusterService/Create](../api-ref/grpc/Cluster/create.md) и выполните запрос, например с помощью [gRPCurl](https://github.com/fullstorydev/grpcurl):

      ```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. Убедитесь, что запрос был выполнен успешно, изучив [ответ сервера](../api-ref/grpc/Cluster/create.md#yandex.cloud.operation.Operation).

{% endlist %}

## Назначить правила для существующего кластера {#set-at-update}

Правила доступа к свойствам сессии каталога можно назначить или обновить в уже существующем кластере Managed Service for Trino.

{% note warning %}
  
Указанные в правилах имена свойств не проверяются на валидность. Ошибка в имени свойства приведет к некорректной работе правила.
  
{% endnote %}

{% list tabs group=instructions %}

- Консоль управления {#console}

  1. В [консоли управления](https://kz.console.yandex.cloud) перейдите в нужный каталог.
  1. Перейдите в сервис **Managed Service for&nbsp;Trino**.
  1. Нажмите на имя нужного кластера.
  1. Перейдите в блок **Настройки доступа** → **Свойства сессии каталога**.
  1. Чтобы добавить правило, нажмите кнопку **Добавить правило** и в открывшемся окне задайте параметры правила:

     1. (Опционально) В поле **Комментарий** введите описание правила.

     1. (Опционально) В поле **Пользователи** выберите пользователей, на которых распространяется правило:
        1. Нажмите кнопку **Добавить**.
        1. В открывшемся списке выберите нужных пользователей. Чтобы найти пользователя, используйте строку поиска над списком.
        1. Чтобы удалить пользователя, выбранного по ошибке, повторно нажмите на него в списке.
        
        Если не выбран ни один пользователь, правило распространяется на всех пользователей.

     1. (Опционально) В поле **Группы** выберите группы пользователей, на которые распространяется правило:
        1. Нажмите кнопку **Добавить**.
        1. В открывшемся списке выберите нужные группы. Чтобы найти группу, используйте строку поиска над списком.
        1. Чтобы удалить группу, выбранную по ошибке, повторно нажмите на нее в списке.
        
        Если не выбрана ни одна группа, правило распространяется на все группы пользователей.

     1. В поле **Allow** укажите, разрешено ли пользователю устанавливать свойство:
        * `No` — запрещено,
        * `Yes` — разрешено.

     1. (Опционально) Укажите, на какие каталоги распространяется правило:
        * **ID** — выберите идентификаторы каталогов. Можно выбрать только те каталоги, которые есть в кластере.
        * **Имя** — выберите имена каталогов. Можно выбрать только каталоги, добавленные в блоке **Каталоги**.
        * **Имя (регулярное выражение)** — введите регулярное выражение для имен каталогов.
        * **Не задано** — правило распространяется на все каталоги кластера.

     1. (Опционально) Укажите, на какие свойства распространяется правило:
        * **Имя** — выберите имена свойств.
        * **Имя (регулярное выражение)** — введите регулярное выражение. Правило распространяется на свойства, имена которых соответствуют регулярному выражению.
        * **Не задано** — правило распространяется на все свойства.

     1. (Опционально) В поле **Свойство сессии** укажите, на какие свойства распространяется правило:
        * **Имя** — выберите имена свойств.
        * **Имя (регулярное выражение)** — введите регулярное выражение. Правило распространяется на свойства, имена которых соответствуют регулярному выражению.
        * **Не задано** — правило распространяется на все свойства.

  1. При необходимости добавьте другие правила аналогичным образом.
  1. Чтобы отредактировать правило:
     1. В строке этого правила нажмите на значок ![trash-bin](../../_assets/console-icons/pencil.svg).
     1. Измените параметры правила и нажмите кнопку **Обновить**.
  1. Чтобы удалить ненужное правило, в строке этого правила нажмите на значок ![trash-bin](../../_assets/console-icons/trash-bin.svg).
  1. Нажмите кнопку **Сохранить изменения**.

- CLI {#cli}

  Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), [установите и инициализируйте его](../../cli/quickstart.md#install).

  По умолчанию используется каталог, указанный при [создании](../../cli/operations/profile/profile-create.md) профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду `yc config set folder-id <идентификатор_каталога>`. Также для любой команды вы можете указать другой каталог с помощью параметров `--folder-name` или `--folder-id`. Если вы обращаетесь к ресурсу по имени, поиск будет выполнен в каталоге по умолчанию. Если вы обращаетесь к ресурсу по идентификатору, поиск будет выполнен глобально — во всех каталогах с учетом прав доступа.

  Чтобы задать правила доступа:

  1. Если правила доступа еще не заданы, создайте файл `access_control.yaml` и добавьте в него следующее содержимое:

     ```yaml
     catalog_session_properties:
       # Правило 1
       - allow: <право_установить_свойство>
         catalog:
           ids:
             any: [<список_идентификаторов_каталогов>]
           names:
             any: [<список_имен_каталогов>]
           name_regexp: <регулярное_выражение>
         property:
           names:
             any: [<список_имен_свойств>]
           name_regexp: <регулярное_выражение>
         groups: [<список_идентификаторов_групп>]
         users: [<список_идентификаторов_пользователей>]
         description: <описание_правила>
       # Правило 2
       - <Параметры_правила_2>
       ...
       # Правило N
       - <Параметры_правила_N>
     ```

     Где:

     * `system_session_properties` — список правил для свойств сессии каталога. Каждое правило включает в себя обязательный параметр `allow`, а также опциональные параметры: `catalog`, `property`, `groups`, `users` и `description`.

     * `allow` — право установить свойство:
       * `YES` — пользователю разрешено установить свойство.
       * `NO` — пользователю запрещено установить свойство.

     * `catalog` — каталоги, на которые распространяется правило. Если блок `catalog` не указан, правило распространяется на все каталоги кластера.
       * `ids` — список идентификаторов каталогов. Указанные каталоги должны существовать.
       * `names` — список имен каталогов. Указанные каталоги должны существовать.
       * `name_regexp` — регулярное выражение. Правило распространяется на каталоги, имена которых соответствуют регулярному выражению.

       Вы можете указать только один из параметров: `ids`, `names` или `name_regexp`.

     * `property` — свойства, на которые распространяется правило. Если блок `property` не указан, правило распространяется на все свойства.
       * `names` — список имен свойств.
       * `name_regexp` — регулярное выражение. Правило распространяется на свойства, имена которых соответствуют регулярному выражению.

       Вы можете указать только один из параметров: `names` или `name_regexp`.

     * Параметры `users` и `groups` определяют пользователей, к которым применяется правило:
     
       * `users` — список идентификаторов пользователей. Правило применяется только к перечисленным пользователям.
     
       * `groups` — список идентификаторов групп. Правило применяется только к пользователям, которые входят хотя бы в одну из перечисленных групп.
     
       Вы можете указать один из параметров или оба. Если указаны оба параметра, правило применяется к каждому пользователю из параметра `users`, входящему хотя бы в одну группу из параметра `groups`. Если оба параметра не указаны, правило применяется ко всем пользователям.
     
     * `description` — описание правила.

  1. Если правила доступа уже заданы, откройте файл `access_control.yaml` и внесите в него изменения. Вы можете:

     * добавить новые правила;
     * изменить параметры существующих правил;
     * удалить ненужные правила.

  1. Выполните команду:

     ```bash
     yc managed-trino cluster set-access-control <имя_или_идентификатор_кластера> \
       --from-file access_control.yaml
     ```

     Идентификатор и имя кластера можно запросить со [списком кластеров в каталоге](cluster-list.md#list-clusters).

- Terraform {#tf}

  1. Откройте актуальный конфигурационный файл Terraform с планом инфраструктуры.
  
      Инструкция по созданию файла описана в разделе [Создание кластера](cluster-create.md).
  
  1. Если правила доступа еще не заданы, добавьте ресурс `yandex_trino_access_control`, содержащий список правил `system_session_properties`.

     ```hcl
     resource "yandex_trino_cluster" "<имя_кластера>" {
       ...
     }

     resource "yandex_trino_catalog" "<имя_каталога_1>" {
       ...
     }

     resource "yandex_trino_catalog" "<имя_каталога_2>" {
       ...
     }

     ...

     resource "yandex_trino_catalog" "<имя_каталога_N>" {
       ...
     }

     resource "yandex_trino_access_control" "trino_access_control" {
       ...
       cluster_id  = yandex_trino_cluster.<имя_кластера>.id
       catalog_session_properties = [
         # Правило 1
         {
           allow         = "<право_установить_свойство>"
           catalog       = {
             ids         = [
               yandex_trino_catalog.<имя_каталога_1>.id,
               yandex_trino_catalog.<имя_каталога_2>.id,
               ... 
               yandex_trino_catalog.<имя_каталога_N>.id
             ]
             name_regexp = "<регулярное_выражение>"
           }
           property      = {
             names       = ["<список_имен_свойств>"]
             name_regexp = "<регулярное_выражение>"
           }
           users         = ["<список_идентификаторов_пользователей>"]
           groups        = ["<список_идентификаторов_групп>"]
           description   = "<описание_правила>"
         },
         # Правило 2
         {
           ... 
         },
         ...
         # Правило N
         {
           ... 
         }
       ]
       ...
     }
     ```

     Где:

     * `catalog_session_properties` — список блоков правил для свойств сессии каталога. Каждое правило включает в себя обязательный параметр `allow`, а также опциональные параметры: `catalog`, `property`, `groups`, `users` и `description`.

     * `allow` — право установить свойство:
       * `YES` — пользователю разрешено установить свойство.
       * `NO` — пользователю запрещено установить свойство.

     * `catalog` — каталоги кластера, на которые распространяется правило. Если блок `catalog` не указан, правило распространяется на все каталоги кластера.
       * `ids` — список идентификаторов каталогов. Указанные каталоги должны существовать или создаваться в том же манифесте.
       * `name_regexp` — регулярное выражение. Правило распространяется на каталоги, имена которых соответствуют регулярному выражению.

       Вы можете указать только один из параметров: `ids` или `name_regexp`.

     * `property` — свойства, на которые распространяется правило. Если блок `property` не указан, правило распространяется на все свойства.
       * `names` — список имен свойств.
       * `name_regexp` — регулярное выражение. Правило распространяется на свойства, имена которых соответствуют регулярному выражению.

       Вы можете указать только один из параметров: `names` или `name_regexp`.

     * Параметры `users` и `groups` определяют пользователей, к которым применяется правило:
     
       * `users` — список идентификаторов пользователей. Правило применяется только к перечисленным пользователям.
     
       * `groups` — список идентификаторов групп. Правило применяется только к пользователям, которые входят хотя бы в одну из перечисленных групп.
     
       Вы можете указать один из параметров или оба. Если указаны оба параметра, правило применяется к каждому пользователю из параметра `users`, входящему хотя бы в одну группу из параметра `groups`. Если оба параметра не указаны, правило применяется ко всем пользователям.
     
     * `description` — описание правила.

  1. Если правила доступа уже заданы, внесите правки в описание ресурса `yandex_trino_access_control`. Вы можете:

     * добавить новые правила;
     * изменить параметры существующих правил;
     * удалить ненужные правила.

  1. Проверьте корректность настроек.
  
      1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.
      1. Выполните команду:
      
         ```bash
         terraform validate
         ```
      
         Если в файлах конфигурации есть ошибки, Terraform на них укажет.
  
  1. Подтвердите изменение ресурсов.
  
      1. Выполните команду для просмотра планируемых изменений:
      
         ```bash
         terraform plan
         ```
      
         Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.
      
      1. Если вас устраивают планируемые изменения, внесите их:
         1. Выполните команду:
      
            ```bash
            terraform apply
            ```
      
         1. Подтвердите изменение ресурсов.
         1. Дождитесь завершения операции.
 
  Подробнее в [документации провайдера Terraform](../../terraform/resources/trino_access_control.md).

- REST API {#api}

  1. [Получите IAM-токен для аутентификации в API](../api-ref/authentication.md) и поместите токен в переменную среды окружения:

      ```bash
      export IAM_TOKEN="<IAM-токен>"
      ```

  1. Если правила доступа еще не заданы, создайте файл `body.json` и добавьте в него следующее содержимое:

      ```json
      {
        "updateMask": "trino.accessControl.systemSessionProperties",
        "trino": {
          "accessControl": {
            "systemSessionProperties": [
              {
                "allow": "<право_установить_свойство>",
                "catalog": {
                  "ids": {
                    "any": [
                      "<список_идентификаторов_каталогов>"
                    ]
                  },
                  "names": {
                    "any": [
                      "<список_имен_каталогов>"
                    ]
                  },
                  "nameRegexp": "<регулярное_выражение>"
                },
                "property": {
                  "names": {
                    "any": [
                      "<список_имен_свойств>"
                    ]
                  },
                  "nameRegexp": "<регулярное_выражение>"
                },
                "users": [
                  "<список_идентификаторов_пользователей>"
                ],
                "groups": [
                  "<список_идентификаторов_групп>"
                ],
                "description": "<описание_правила>"
              },
              {
                <Блок_правила_2>
              },
              ...
              {
                <Блок_правила_N>
              }
            ]
          }
        }
      }
      ```

      Где:

      * `updateMask` — перечень изменяемых параметров в строку через запятую.

          {% note warning %}

          При изменении кластера все параметры изменяемого объекта, которые не были явно переданы в запросе, будут переопределены на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре `updateMask`.

          {% endnote %}

      * `accessControl` — конфигурация прав доступа в рамках кластера.

      * `systemSessionProperties` — список блоков правил для системных свойств сессии. Каждое правило включает в себя обязательный параметр `allow`, а также опциональные параметры: `property`, `groups`, `users` и `description`.

      * `allow` — право установить свойство:
        * `YES` — пользователю разрешено установить свойство.
        * `NO` — пользователю запрещено установить свойство.

      * `catalog` — каталоги, на которые распространяется правило. Если блок `catalog` не указан, правило распространяется на все каталоги кластера.
        * `ids` — список идентификаторов каталогов. Указанные каталоги должны существовать.
        * `names` — список имен каталогов. Указанные каталоги должны существовать.
        * `nameRegexp` — регулярное выражение. Правило распространяется на каталоги, имена которых соответствуют регулярному выражению.

        Блок `catalog` должен содержать либо один из вложенных блоков `ids` или `names`, либо параметр `name_regexp`.

      * `property` — свойства, на которые распространяется правило. Если блок `property` не указан, правило распространяется на все свойства.
        * `names` — список имен свойств.
        * `nameRegexp` — регулярное выражение. Правило распространяется на свойства, имена которых соответствуют регулярному выражению.

        Блок `property` должен содержать либо вложенный блок `names`, либо параметр `nameRegexp`.

      * Параметры `users` и `groups` определяют пользователей, к которым применяется правило:
      
        * `users` — список идентификаторов пользователей. Правило применяется только к перечисленным пользователям.
      
        * `groups` — список идентификаторов групп. Правило применяется только к пользователям, которые входят хотя бы в одну из перечисленных групп.
      
        Вы можете указать один из параметров или оба. Если указаны оба параметра, правило применяется к каждому пользователю из параметра `users`, входящему хотя бы в одну группу из параметра `groups`. Если оба параметра не указаны, правило применяется ко всем пользователям.
      
      * `description` — описание правила.

  1. Если правила уже заданы, откройте существующий файл `body.json` с правилами и внесите в него правки. Вы можете:

     * добавить новые правила;
     * изменить параметры существующих правил;
     * удалить ненужные правила.

  1. Воспользуйтесь методом [Cluster.Update](../api-ref/Cluster/update.md) и выполните запрос, например с помощью [cURL](https://curl.se/):

      ```bash
      curl \
        --request PATCH \
        --header "Authorization: Bearer $IAM_TOKEN" \
        --url 'https://trino.api.cloud.yandex.net/managed-trino/v1/clusters/<идентификатор_кластера>'
        --data '@body.json'
      ```

      Идентификатор кластера можно получить со [списком кластеров](cluster-list.md#list-clusters) в каталоге.

  1. Убедитесь, что запрос был выполнен успешно, изучив [ответ сервера](../api-ref/Cluster/update.md#yandex.cloud.operation.Operation).

- gRPC API {#grpc-api}

  1. [Получите IAM-токен для аутентификации в API](../api-ref/authentication.md) и поместите токен в переменную среды окружения:

      ```bash
      export IAM_TOKEN="<IAM-токен>"
      ```

  1. Клонируйте репозиторий [cloudapi](https://github.com/yandex-cloud/cloudapi):
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Далее предполагается, что содержимое репозитория находится в директории `~/cloudapi/`.

  1. Если правила доступа еще не заданы, создайте файл `body.json` и добавьте в него следующее содержимое:

      ```json
      {
        "cluster_id": "<идентификатор_кластера>",
        "update_mask": {
          "paths": [
            "trino.access_control.catalog_session_properties"
          ]
        },
        "trino": {
          "access_control": {
            "catalog_session_properties": [
              {
                "allow": "<право_установить_свойство>",
                "catalog": {
                  "ids": {
                    "any": [
                      "<список_идентификаторов_каталогов>"
                    ]
                  },
                  "names": {
                    "any": [
                      "<список_имен_каталогов>"
                    ]
                  },
                  "name_regexp": "<регулярное_выражение>"
                },
                "property": {
                  "names": {
                    "any": [
                      "<список_имен_свойств>"
                    ]
                  },
                  "name_regexp": "<регулярное_выражение>"
                },
                "users": [
                  "<список_идентификаторов_пользователей>"
                ],
                "groups": [
                  "<список_идентификаторов_групп>"
                ],
                "description": "<описание_правила>"
              },
              {
                <Блок_правила_2>
              },
              ...
              {
                <Блок_правила_N>
              }
            ]
          }
        }
      }
      ```

      Где:

      * `cluster_id` — идентификатор кластера.
          
          Идентификатор кластера можно получить со [списком кластеров](cluster-list.md#list-clusters) в каталоге.

      * `update_mask` — перечень изменяемых параметров в виде массива строк `paths[]`.

          {% cut "Формат перечисления настроек" %}

          ```yaml
          "update_mask": {
            "paths": [
              "<настройка_1>",
              "<настройка_2>",
              ...
              "<настройка_N>"
            ]
          }
          ```

          {% endcut %}

          {% note warning %}

          При изменении кластера все параметры изменяемого объекта, которые не были явно переданы в запросе, будут переопределены на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре `update_mask`.

          {% endnote %}

      * `access_control` — конфигурация прав доступа в рамках кластера.

      * `system_session_properties` — список блоков правил для свойств сессии каталога. Каждое правило включает в себя обязательный параметр `allow`, а также опциональные параметры: `catalog`, `property`, `groups`, `users` и `description`.

      * `allow` — право установить свойство:
        * `YES` — пользователю разрешено установить свойство.
        * `NO` — пользователю запрещено установить свойство.

      * `catalog` — каталоги, на которые распространяется правило. Если блок `catalog` не указан, правило распространяется на все каталоги кластера.
        * `ids` — список идентификаторов каталогов. Указанные каталоги должны существовать.
        * `names` — список имен каталогов. Указанные каталоги должны существовать.
        * `name_regexp` — регулярное выражение. Правило распространяется на каталоги, имена которых соответствуют регулярному выражению.

        Блок `catalog` должен содержать либо один из вложенных блоков `ids` или `names`, либо параметр `name_regexp`.

      * `property` — свойства, на которые распространяется правило. Если блок `property` не указан, правило распространяется на все свойства.
        * `names` — список имен свойств.
        * `name_regexp` — регулярное выражение. Правило распространяется на свойства, имена которых соответствуют регулярному выражению.

        Блок `property` должен содержать либо вложенный блок `names`, либо параметр `name_regexp`.

      * Параметры `users` и `groups` определяют пользователей, к которым применяется правило:
      
        * `users` — список идентификаторов пользователей. Правило применяется только к перечисленным пользователям.
      
        * `groups` — список идентификаторов групп. Правило применяется только к пользователям, которые входят хотя бы в одну из перечисленных групп.
      
        Вы можете указать один из параметров или оба. Если указаны оба параметра, правило применяется к каждому пользователю из параметра `users`, входящему хотя бы в одну группу из параметра `groups`. Если оба параметра не указаны, правило применяется ко всем пользователям.
      
      * `description` — описание правила.

  1. Если правила уже заданы, откройте существующий файл `body.json` с правилами и внесите в него правки. Вы можете:

     * добавить новые правила;
     * изменить параметры существующих правил;
     * удалить ненужные правила.

  1. Воспользуйтесь вызовом [ClusterService.Update](../api-ref/grpc/Cluster/update.md) и выполните запрос, например с помощью [gRPCurl](https://github.com/fullstorydev/grpcurl):

      ```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. Убедитесь, что запрос был выполнен успешно, изучив [ответ сервера](../api-ref/grpc/Cluster/update.md#yandex.cloud.operation.Operation).

{% endlist %}

## Пример назначения правил доступа к свойствам сессии каталога {#example}

Допустим, вам нужно настроить правила доступа к свойствам сессии каталога:
1. Разрешить устанавливать любые свойства пользователям, входящим в группу с идентификатором `admins_group_id`.
1. Разрешить пользователям из группы с идентификатором `analytics_group_id` устанавливать свойства с именами вида `parquet_.*` в каталоге с идентификатором `hive_cat_id`.
1. Всем остальным пользователям запретить устанавливать свойства.

{% list tabs group=instructions %}

- CLI {#cli}

  Файл `access_control.yaml` для такого набора правил выглядит так:

  ```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}

  Конфигурационный файл для такого набора правил выглядит так:

  ```hcl
  resource "yandex_trino_access_control" "trino_access_control" {
    ...
    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}

  Файл `body.json` для такого набора правил выглядит так:

  ```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}

  Файл `body.json` для такого набора правил выглядит так:

  ```json
  {
    "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 %}