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

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

Правила доступа к объектам каталогов позволяют ограничивать права пользователей сразу на все объекты одного или нескольких каталогов в кластере Managed Service for Trino. Чтобы управлять доступом к отдельным объектам кластера, используйте более гранулярные правила (например правила доступа к [схемам](access-control-schemas.md) или [таблицам](access-control-tables.md)).

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

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

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

{% 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. В поле **Разрешения** выберите уровень доступа к объектам каталогов:
        * `NONE` — запрещены любые операции над объектами каталога.
        * `ALL` — разрешены любые операции. В этом случае доступ пользователей к объектам каталога определяется более гранулярными правилами, например правилами для таблиц.
        * `READ_ONLY` — разрешены только операции чтения (например, чтение данных из таблицы).

     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
     catalogs:
       # Правило 1
       - permission: <уровень_доступа>
         catalog:
           name_regexp: <регулярное_выражение>
         groups: [<список_идентификаторов_групп>]
         users: [<список_идентификаторов_пользователей>]
         description: <описание_правила>
       # Правило 2
       - <Параметры_правила_2>
       ...
       # Правило N
       - <Параметры_правила_N>
     ```

     Где:

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

     * `permission` — уровень доступа пользователя или группы к каталогам в рамках правила:
       * `NONE` — запрещены любые операции над объектами каталога.
       * `READ_ONLY` — разрешены только операции чтения (например, чтение данных из таблицы).
       * `ALL` — разрешены любые операции. В этом случае доступ пользователей к объектам каталога определяется более гранулярными правилами, например правилами для таблиц.

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

     * Параметры `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`, содержащий список правил `catalogs`.
 
     ```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
       catalogs = [
         # Правило 1
         {
           permission    = "<уровень_доступа>"
           catalog       = {
             ids         = [
               yandex_trino_catalog.<имя_каталога_1>.id,
               yandex_trino_catalog.<имя_каталога_2>.id,
               ... 
               yandex_trino_catalog.<имя_каталога_N>.id
             ]
             name_regexp = "<регулярное_выражение>"
           }
           users         = ["<список_идентификаторов_пользователей>"]
           groups        = ["<список_идентификаторов_групп>"]
           description   = "<описание_правила>"
         },
         # Правило 2
         {
           ... 
         },
         ...
         # Правило N
         {
           ... 
         }
       ]
       ...
     }
     ```

     Где:

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

     * `permission` — уровень доступа пользователя или группы к каталогам в рамках правила:
       * `NONE` — запрещены любые операции над объектами каталога.
       * `READ_ONLY` — разрешены только операции чтения (например, чтение данных из таблицы).
       * `ALL` — разрешены любые операции. В этом случае доступ пользователей к объектам каталога определяется более гранулярными правилами, например правилами для таблиц.

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

       Вы можете указать только один из параметров: `ids` или `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": {
            "catalogs": [
              {
                "permission": "<уровень_доступа>",
                "catalog": {
                  "names": {
                    "any": [
                      "<имя_каталога_1>",
                      "<имя_каталога_2>",
                      ...
                      "<имя_каталога_N>"
                    ]
                  },
                  "nameRegexp": "<регулярное_выражение>"
                },
                "users": [
                  "<список_идентификаторов_пользователей>"
                ],
                "groups": [
                  "<список_идентификаторов_групп>"
                ],
                "description": "<описание_правила>"
              },
              {
                <Блок_правила_2>
              },
              ...
              {
                <Блок_правила_N>
              }
            ]
          }
        }
      }
      ```

      Где:

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

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

      * `permission` — уровень доступа пользователя или группы к каталогам в рамках правила:
        * `NONE` — запрещены любые операции над объектами каталога.
        * `READ_ONLY` — разрешены только операции чтения (например, чтение данных из таблицы).
        * `ALL` — разрешены любые операции. В этом случае доступ пользователей к объектам каталога определяется более гранулярными правилами, например правилами для таблиц.

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

        Блок `catalog` должен содержать либо вложенный блок `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": {
            "catalogs": [
              {
                "permission": "<уровень_доступа>",
                "catalog": {
                  "names": {
                    "any": [
                      "<имя_каталога_1>",
                      "<имя_каталога_2>",
                      ...
                      "<имя_каталога_N>"
                    ]
                  },
                  "name_regexp": "<регулярное_выражение>"
                },
                "users": [
                  "<список_идентификаторов_пользователей>"
                ],
                "groups": [
                  "<список_идентификаторов_групп>"
                ],
                "description": "<описание_правила>"
              },
              {
                <Блок_правила_2>
              },
              ...
              {
                <Блок_правила_N>
              }
            ]
          }
        }
      }
      ```

      Где:

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

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

      * `permission` — уровень доступа пользователя или группы к каталогам в рамках правила:
        * `NONE` — запрещены любые операции над объектами каталога.
        * `READ_ONLY` — разрешены только операции чтения (например, чтение данных из таблицы).
        * `ALL` — разрешены любые операции. В этом случае доступ пользователей к объектам каталога определяется более гранулярными правилами, например правилами для таблиц.

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

        Блок `catalog` должен содержать либо вложенный блок `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.

{% 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. В поле **Разрешения** выберите уровень доступа к объектам каталогов:
        * `NONE` — запрещены любые операции над объектами каталога.
        * `ALL` — разрешены любые операции. В этом случае доступ пользователей к объектам каталога определяется более гранулярными правилами, например правилами для таблиц.
        * `READ_ONLY` — разрешены только операции чтения (например, чтение данных из таблицы).

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

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

     Где:

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

     * `permission` — уровень доступа пользователя или группы к каталогам в рамках правила:
       * `NONE` — запрещены любые операции над объектами каталога.
       * `READ_ONLY` — разрешены только операции чтения (например, чтение данных из таблицы).
       * `ALL` — разрешены любые операции. В этом случае доступ пользователей к объектам каталога определяется более гранулярными правилами, например правилами для таблиц.

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

       Вы можете указать только один из параметров: `ids`, `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`, содержащий список правил `catalogs`.
 
     ```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
       catalogs = [
         # Правило 1
         {
           permission    = "<уровень_доступа>"
           catalog       = {
             ids         = [
               yandex_trino_catalog.<имя_каталога_1>.id,
               yandex_trino_catalog.<имя_каталога_2>.id,
               ... 
               yandex_trino_catalog.<имя_каталога_N>.id
             ]
             name_regexp = "<регулярное_выражение>"
           }
           users         = ["<список_идентификаторов_пользователей>"]
           groups        = ["<список_идентификаторов_групп>"]
           description   = "<описание_правила>"
         },
         # Правило 2
         {
           ... 
         },
         ...
         # Правило N
         {
           ... 
         }
       ]
       ...
     }
     ```

     Где:

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

     * `permission` — уровень доступа пользователя или группы к каталогам в рамках правила:
       * `NONE` — запрещены любые операции над объектами каталога.
       * `READ_ONLY` — разрешены только операции чтения (например, чтение данных из таблицы).
       * `ALL` — разрешены любые операции. В этом случае доступ пользователей к объектам каталога определяется более гранулярными правилами, например правилами для таблиц.

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

       Вы можете указать только один из параметров: `ids` или `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.catalogs",
        "trino": {
          "accessControl": {
            "catalogs": [
              {
                "permission": "<уровень_доступа>",
                "catalog": {
                  "nameRegexp": "<регулярное_выражение>",
                  "ids": {
                    "any": [
                      "<список_идентификаторов_каталогов>"
                    ]
                  },
                  "names": {
                    "any": [
                      "<список_имен_каталогов>"
                    ]
                  }
                },
                "users": [
                  "<список_идентификаторов_пользователей>"
                ],
                "groups": [
                  "<список_идентификаторов_групп>"
                ],
                "description": "<описание_правила>"
              },
              {
                <Блок_правила_2>
              },
              ...
              {
                <Блок_правила_N>
              }
            ]
          }
        }
      }
      ```

      Где:

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

          {% note warning %}

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

          {% endnote %}

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

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

      * `permission` — уровень доступа пользователя или группы к каталогам в рамках правила:
        * `NONE` — запрещены любые операции над объектами каталога.
        * `READ_ONLY` — разрешены только операции чтения (например, чтение данных из таблицы).
        * `ALL` — разрешены любые операции. В этом случае доступ пользователей к объектам каталога определяется более гранулярными правилами, например правилами для таблиц.

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

        Блок `catalog` должен содержать либо один из вложенных блоков `ids` или `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.catalogs"
          ]
        },
        "trino": {
          "access_control": {
            "catalogs": [
              {
                "permission": "<уровень_доступа>",
                "catalog": {
                  "name_regexp": "<регулярное_выражение>",
                  "ids": {
                    "any": [
                      "<список_идентификаторов_каталогов>"
                    ]
                  },
                  "names": {
                    "any": [
                      "<список_имен_каталогов>"
                    ]
                  }
                },
                "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` — конфигурация прав доступа в рамках кластера.

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

      * `permission` — уровень доступа пользователя или группы к каталогам в рамках правила:
        * `NONE` — запрещены любые операции над объектами каталога.
        * `READ_ONLY` — разрешены только операции чтения (например, чтение данных из таблицы).
        * `ALL` — разрешены любые операции. В этом случае доступ пользователей к объектам каталога определяется более гранулярными правилами, например правилами для таблиц.

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

        Блок `catalog` должен содержать либо один из вложенных блоков `ids` или `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}

Допустим, вам нужно настроить правила доступа к объектам в каталогах кластера Trino:
1. Запретить любые действия над объектами во всех каталогах кластера пользователям из группы с идентификатором `banned_group_id`.
1. Разрешить любые операции над объектами в каталогах с идентификаторами `cat1_id` и `cat2_id` пользователям с идентификаторами `user1_id` и `user2_id`, если они входят в группу с идентификатором `analytics_group_id`.
1. Разрешить всем пользователям чтение объектов в каталогах с именами, удовлетворяющими регулярному выражению `.*_prod`.

{% list tabs group=instructions %}

- CLI {#cli}

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

  ```yaml
  catalogs:
    - permission: NONE
      groups:
        - banned_group_id

    - permission: ALL
      catalog:
        ids:
          any:
            - cat1_id
            - cat2_id
      groups:
        - analytics_group_id
      users:
        - user1_id
        - user2_id

    - permission: READ_ONLY
      catalog:
        name_regexp: ".*_prod"
  ```

- Terraform {#tf}

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

  ```hcl
  resource "yandex_trino_access_control" "trino_access_control" {
    ...
    cluster_id  = <идентификатор_кластера>
    catalogs = [
      {
        permission    = "NONE"
        groups        = ["banned_group_id"]
      },
      {
        permission    = "ALL"
        catalog       = {
          ids         = ["cat1_id", "cat2_id"]
        }
        users         = ["user1_id", "user2_id"]
        groups        = ["analytics_group_id"]
      },
      {
        permission    = "READ_ONLY"
        catalog       = {
          name_regexp = ".*_prod"
        }
      }
    ]
    ...
  }
  ```

- REST API {#api}

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

  ```json
  {
    "updateMask": "trino.accessControl.catalogs",
    "trino": {
      "accessControl": {
        "catalogs": [
          {
            "permission": "NONE",
            "groups": [
              "banned_group_id"
            ]
          },
          {
            "permission": "ALL",
            "catalog": {
              "ids": {
                "any": [
                  "cat1_id",
                  "cat2_id"
                ]
              }
            },
            "users": [
              "user1_id",
              "user2_id"
            ],
            "groups": [
              "analytics_group_id"
            ]
          },
          {
            "permission": "READ_ONLY",
            "catalog": {
              "nameRegexp": ".*_prod"
            }
          }
        ]
      }
    }
  }
  ```

- gRPC API {#grpc-api}

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

  ```json
  {
    "cluster_id": "<идентификатор_кластера>",
    "update_mask": {
      "paths": [
        "trino.access_control.catalogs"
      ]
    },
    "trino": {
      "access_control": {
        "catalogs": [
          {
            "permission": "NONE",
            "groups": [
              "banned_group_id"
            ]
          },
          {
            "permission": "ALL",
            "catalog": {
              "ids": {
                "any": [
                  "cat1_id",
                  "cat2_id"
                ]
              }
            },
            "users": [
              "user1_id",
              "user2_id"
            ],
            "groups": [
              "analytics_group_id"
            ]
          },
          {
            "permission": "READ_ONLY",
            "catalog": {
              "name_regexp": ".*_prod"
            }
          }
        ]
      }
    }
  }
  ```

{% endlist %}