Создать HTTP-роутер для gRPC-трафика

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

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

   yc alb http-router create --help
   

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

   yc alb http-router create <имя_HTTP-роутера>
   

   Результат:

   id: a5dcsselagj4********
   name: <имя_HTTP-роутера>
   folder_id: aoerb349v3h4********
   created_at: "2022-06-16T21:04:59.438292069Z"
   

3. Посмотрите описание команды CLI для создания виртуального хоста:

   yc alb virtual-host create --help
   

4. Создайте виртуальный хост, указав его имя и настройки:

   yc alb virtual-host create <имя_виртуального_хоста> \
     --http-router-name <имя_HTTP-роутера> \
     --authority <домен_1>,<домен_2>,...,<домен_n> \
     --modify-request-header name=Accept-Language,append=ru-RU \
     --modify-response-header name=Accept-Charset,replace=utf-8 \
     --rate-limit rps=100,all-requests \
     --security-profile-id <идентификатор_профиля_безопасности>
   

   Где:

   • --http-router-name — имя HTTP-роутера.

     Вместо имени HTTP-роутера вы можете указать его идентификатор в параметре --http-router-id.

   • --authority — список доменов для заголовков Host для HTTP/1.1 или authority для HTTP/2, которые будут связаны с этим виртуальным хостом. Несколько значений указываются через запятую. Поддерживаются символы подстановки, например *.foo.com или *-bar.foo.com. Для gRPC-трафика вы можете указать IP-адрес балансировщика.

     Необязательный параметр. Если значение не задано, на виртуальный хост будет направляться весь трафик.

   • --modify-request-header — настройки модификации HTTP-заголовка запроса в формате <свойство>=<значение>. Возможные свойства:

     • name — имя модифицируемого заголовка. Например: Host, User-Agent, X-Forwarded-For, Strict-Transport-Security и т.п.
     • append — добавить строку к текущему значению заголовка.
     • replace — полностью заменить текущее значение заголовка.
     • rename — изменить имя заголовка. Значение заголовка при этом не изменяется.
     • remove — удалить заголовок. При этом будет удалено не только значение заголовка, но и сам заголовок.

     Чтобы изменить несколько HTTP-заголовков в запросе, задайте в команде параметр --modify-request-header необходимое количество раз.

     Необязательный параметр: если не задан, заголовки запроса передаются в бэкенд в неизменном виде.

   • --modify-response-header — настройки модификации HTTP-заголовка ответа в формате <свойство>=<значение>. Возможные свойства:

     • name — имя модифицируемого заголовка. Например: Host, User-Agent, X-Forwarded-For, Strict-Transport-Security и т.п.
     • append — добавить строку к текущему значению заголовка.
     • replace — полностью заменить текущее значение заголовка.
     • rename — изменить имя заголовка. Значение заголовка при этом не изменяется.
     • remove — удалить заголовок. При этом будет удалено не только значение заголовка, но и сам заголовок.

     Чтобы изменить несколько HTTP-заголовков в ответе, задайте в команде параметр --modify-response-header необходимое количество раз.

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

   • --rate-limit — ограничение на частоту запросов. Возможные свойства:

     • rps или rpm — количество запросов, которые можно принять в секунду или в минуту.
     • all-requests — ограничение на все входящие запросы.
     • requests-per-ip — ограничение на количество запросов для каждого IP-адреса клиента в отдельности.

     Для одного виртуального хоста вы можете задать только один вид ограничения: либо свойство all-requests, либо — requests-per-ip.

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

   • --security-profile-id — идентификатор профиля безопасности сервиса Yandex Smart Web Security. Профиль безопасности позволяет настроить фильтрацию входящих запросов, подключить WAF и установить лимиты на количество запросов для защиты от вредоносной активности. Подробнее см. Профили безопасности. Необязательный параметр.

   Результат:

   name: test-virtual-host
   authority:
     - example.com
     - example.org
   modify_request_headers:
     - name: Accept-Language
       append: ru-RU
     - name: Accept-Charset
       replace: utf-8
   route_options:
     security_profile_id: fevu5fnuk6vf********
   rate_limit:
     all_requests:
       per_second: "100"
   

5. Посмотрите описание команды CLI для добавления маршрута в конец списка маршрутов виртуального хоста:

   yc alb virtual-host append-grpc-route --help
   

6. Добавьте маршрут, указав его имя и дополнительные параметры:

   yc alb virtual-host append-grpc-route <имя_маршрута> \
     --http-router-name <имя_HTTP-роутера> \
     --virtual-host-name <имя_виртуального_хоста> \
     --exact-fqmn-match <полный_FQMN> \
     --prefix-fqmn-match <префикс_FQMN> \
     --regex-fqmn-match <регулярное_выражение> \
     --backend-group-name <имя_группы_бэкендов> \
     --request-max-timeout <таймаут_запроса>s \
     --request-idle-timeout <таймаут_ожидания_запроса>s \
     --rate-limit rps=<лимит_запросов>,requests-per-ip \
     --disable-security-profile
   

   Где:

   • --http-router-name — имя HTTP-роутера, в котором создается маршрут.

     Вместо имени HTTP-роутера вы можете указать его идентификатор в параметре --http-router-id.

   • --virtual-host-name — имя виртуального хоста, в котором создается маршрут.

   • Параметры с условиями маршрутизации на основе FQMN:

     • --exact-fqmn-match — маршрутизировать запросы, FQMN в которых идентичен заданному.
     • --prefix-fqmn-match — маршрутизировать запросы, FQMN в которых начинается с заданного префикса. Например, вы можете указать первое слово в имени сервиса: /helloworld.
     • --regex-fqmn-match — маршрутизировать запросы, FQMN в которых удовлетворяет заданному регулярному выражению стандарта RE2. Например: \/[a-z]{10}[0-9]{3}.

     Важно

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

     Примечание

     Параметры --exact-fqmn-match, --prefix-fqmn-match и --regex-fqmn-match — взаимоисключающие: вы можете использовать только один из них.

   • --backend-group-name — имя группы бэкендов, расположенной в том же каталоге, в котором находятся HTTP-роутер и виртуальный хост, для которых вы создаете маршрут.

     Вместо имени группы бэкендов вы можете указать ее идентификатор в параметре --backend-group-id.

   • --request-max-timeout — максимальное время, на которое может быть установлено соединение. Клиент может указать в запросе HTTP-заголовок grpc-timeout с меньшим значением таймаута.

   • --request-idle-timeout — максимальное время в секундах, в течение которого соединение может простаивать без передачи данных.

   • --rate-limit — ограничение на частоту запросов. Возможные свойства:

     • rps или rpm — количество запросов, которые можно принять в секунду или в минуту.
     • all-requests — ограничение на все входящие запросы.
     • requests-per-ip — ограничение на количество запросов для каждого IP-адреса клиента в отдельности.

     Для одного маршрута вы можете задать только один вид ограничения: либо свойство all-requests, либо — requests-per-ip.

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

   • --disable-security-profile — параметр, отключающий для маршрута использование профиля безопасности сервиса Yandex Smart Web Security, заданного для виртуального хоста. Профиль безопасности позволяет настроить фильтрацию входящих запросов, подключить WAF и установить лимиты на количество запросов для защиты от вредоносной активности. Подробнее см. в разделе Профили безопасности. Необязательный параметр. По умолчанию профиль безопасности, привязанный к виртуальному хосту, действует в отношении всех создаваемых маршрутов.

   Результат:

   name: test-virtual-host
   authority:
     - example.com
   routes:
     - name: my-first-route
       grpc:
         match:
           fqmn:
             prefix_match: /
         route:
           backend_group_id: ds7dq9nsrgpc********
           max_timeout: 60s
           idle_timeout: 5s
           auto_host_rewrite: false
     - name: my-second-route
       grpc:
         match:
           fqmn:
             prefix_match: helloworld/
         route:
           backend_group_id: ds7dq9nsrgpc********
           max_timeout: 10s
           idle_timeout: 5s
           rate_limit:
             requests_per_ip:
               per_second: "4"
       disable_security_profile: true
   modify_request_headers:
     - name: Accept-Language
       append: ru-RU
   route_options:
     security_profile_id: fevu5fnuk6vf********
   rate_limit:
     all_requests:
       per_second: "100"
   

   Подробную информацию о команде yc alb virtual-host append-grpc-route с полным перечнем параметров см. в справочнике CLI.

Terraform позволяет быстро создать облачную инфраструктуру в Yandex Cloud и управлять ею с помощью файлов конфигураций. В файлах конфигураций хранится описание инфраструктуры на языке HCL (HashiCorp Configuration Language). При изменении файлов конфигураций Terraform автоматически определяет, какая часть вашей конфигурации уже развернута, что следует добавить или удалить.

Terraform распространяется под лицензией Business Source License, а провайдер Yandex Cloud для Terraform — под лицензией MPL-2.0.

Подробную информацию о ресурсах провайдера смотрите в документации на сайте Terraform или в зеркале.

Если у вас еще нет Terraform, установите его и настройте провайдер Yandex Cloud.

1. Опишите в конфигурационном файле параметры HTTP-роутера и виртуального хоста:

   resource "yandex_alb_http_router" "tf-router" {
     name          = "<имя_HTTP-роутера>"
     labels        = {
       tf-label    = "tf-label-value"
       empty-label = ""
     }
   }
   
   resource "yandex_alb_virtual_host" "my-virtual-host" {
     name           = "<имя_виртуального_хоста>"
     http_router_id = yandex_alb_http_router.tf-router.id
   
     rate_limit {
       all_requests {
         per_second = <количество_запросов_в_секунду>
         # или per_minute = <количество_запросов_в_минуту>
       }
       requests_per_ip {
         per_second = <количество_запросов_в_секунду>
         # или per_minute = <количество_запросов_в_минуту>
       }
     }
   
     route {
       name                      = "<имя_маршрута>"
       disable_security_profile  = true|false
   
       grpc_route {
         grpc_match {
           fqmn {
             prefix = "/<префикс_FQMN_запроса>"
             # или exact = "<FQMN_запроса>"
             # или regex = "<регулярное_выражение>"
           }
         }
   
         grpc_route_action {
           backend_group_id  = "<идентификатор_группы_бэкендов>"
           host_rewrite      = "<значение_заголовка_Host>"
           max_timeout       = "<таймаут_соединения>s"
           idle_timeout      = "<таймаут-простоя>s"
           rate_limit {
             all_requests {
               per_second = <количество_запросов_в_секунду>
               # или per_minute = <количество_запросов_в_минуту>
             }
             requests_per_ip {
               per_second = <количество_запросов_в_секунду>
               # или per_minute = <количество_запросов_в_минуту>
             }
           }
         }
       }
     }
   
     authority        = ["<домен_1>","<домен_2>",...,"<домен_n>"]
   
     modify_request_headers {
       name           = "<имя_заголовка>"
       append         = "<добавляемая_в_содержимое_заголовка_строка>"
       # или replace  = "<новое_содержимое_заголовка>"
       # или remove   = true|false
     }
   
     modify_response_headers {
       name           = "<имя_заголовка>"
       append         = "<добавляемая_в_содержимое_заголовка_строка>"
       # или replace  = "<новое_содержимое_заголовка>"
       # или remove   = true|false
     }
   
     route_options {
       security_profile_id = "<идентификатор_профиля_безопасности>"
     }
   }
   

   Где:

   • yandex_alb_http_router — описание HTTP-роутера:

     • name — имя HTTP-роутера. Формат имени:

       • длина — от 2 до 63 символов;
       • может содержать строчные буквы латинского алфавита, цифры и дефисы;
       • первый символ — буква, последний — не дефис.

     • labels — метки для HTTP-роутера. Укажите пару ключ — значение.

   • yandex_alb_virtual_host — описание виртуального хоста:

     • name — имя виртуального хоста. Формат имени:

       • длина — от 2 до 63 символов;
       • может содержать строчные буквы латинского алфавита, цифры и дефисы;
       • первый символ — буква, последний — не дефис.

     • http_router_id — идентификатор HTTP-роутера.

     • rate_limit — (опционально) ограничение частоты запросов для всего виртуального хоста.

       • all_requests — (опционально) ограничение всех запросов в секунду или в минуту:

         • per_second — максимальное количество входящих запросов, которые могут поступать на виртуальный хост за одну секунду.
         • per_minute — максимальное количество входящих запросов, которые могут поступать на виртуальный хост за одну минуту.

         Параметры per_second и per_minute — взаимоисключающие: вы можете использовать только один из них.

       • requests_per_ip — (опционально) дополнительное ограничение запросов для каждого IP-адреса в секунду или в минуту:

         • per_second — максимальное количество входящих запросов с одного IP-адреса, которые могут поступать на виртуальный хост за одну секунду.
         • per_minute — максимальное количество входящих запросов с одного IP-адреса, которые могут поступать на виртуальный хост за одну минуту.

         Параметры per_second и per_minute — взаимоисключающие: вы можете использовать только один из них.

     • route — описание маршрута виртуального хоста:

       • name — имя маршрута.
       • disable_security_profile — (опционально) опция отключения профиля безопасности сервиса Yandex Smart Web Security. Возможные значения: true (профиль отключен) или false (профиль включен). По умолчанию профиль безопасности включен (значение false).

       • grpc_route — описание маршрута для gRPC-трафика:

         • grpc_match.fqmn — (опционально) параметр для фильтрации входящих gRPC-запросов по FQMN:

           • exact — маршрутизировать запросы, FQMN в которых идентичен заданному.
           • prefix — маршрутизировать запросы, FQMN в которых начинается с заданного префикса. Например, вы можете указать первое слово в имени сервиса: /helloworld.
           • regex — маршрутизировать запросы, FQMN в которых удовлетворяет заданному регулярному выражению стандарта RE2. Например: \/[a-z]{10}[0-9]{3}.

           Параметры exact, prefix и regex — взаимоисключающие: вы можете использовать только один из них.

         • grpc_route_action — параметр для указания действия с gRPC-трафиком.

           • backend_group_id — идентификатор группы бэкендов, расположенной в том же каталоге, в котором находятся HTTP-роутер и виртуальный хост, для которых создается маршрут.
           • host_rewrite — (опционально) замена заголовка Host в запросе на указанное значение. Вместо параметра host_rewrite вы можете указать параметр auto_host_rewrite — в этом случае заголовок Host в запросе автоматически будет заменяться на адрес целевой виртуальной машины.
           • max_timeout — (опционально) максимальный таймаут ожидания запроса в секундах. Клиент может указать в запросе HTTP-заголовок grpc-timeout с меньшим значением таймаута. Значение по умолчанию — 60 секунд.
           • idle_timeout — (опционально) максимальное время keep-alive, в течение которого соединение может простаивать без передачи данных. Если не задано, соединение без передачи данных будет сразу разрываться.

           • rate_limit — (опционально) параметр для ограничения количества запросов за единицу времени:

             • all_requests — (опционально) ограничение на все входящие запросы:

               • per_second — максимальное количество входящих запросов, которые могут поступать в маршрут за одну секунду.
               • per_minute — максимальное количество входящих запросов, которые могут поступать в маршрут за одну минуту.

               Параметры per_second и per_minute — взаимоисключающие: вы можете использовать только один из них.

             • requests_per_ip — (опционально) ограничение на входящие запросы с одного IP-адреса:

               • per_second — максимальное количество входящих запросов с одного IP-адреса, которые могут поступать в маршрут за одну секунду.
               • per_minute — максимальное количество входящих запросов с одного IP-адреса, которые могут поступать в маршрут за одну минуту.

               Параметры per_second и per_minute — взаимоисключающие: вы можете использовать только один из них.

     • authority — домены для заголовков Host для HTTP/1.1 или authority для HTTP/2, которые будут связаны с этим виртуальным хостом. Поддерживаются символы подстановки, например *.foo.com или *-bar.foo.com. Для gRPC-трафика вы можете указать * или IP-адрес балансировщика.

       Необязательный параметр. Если значение не задано, на виртуальный хост будет направляться весь трафик.

     • modify_request_headers — настройки модификации HTTP-заголовков запроса. Возможные параметры:

       • name — имя модифицируемого заголовка. Например: Host, User-Agent, X-Forwarded-For, Strict-Transport-Security и т.п.
       • append — добавить строку к текущему значению заголовка.
       • replace — полностью заменить текущее значение заголовка.
       • remove — удалить заголовок. При этом будет удалено не только значение заголовка, но и сам заголовок. Возможные значения: true или false.

       Необязательный параметр: если не задан, заголовки запроса передаются в бэкенд в неизменном виде.

     • modify_response_headers — настройки модификации HTTP-заголовков ответа. Возможные параметры:

       • name — имя модифицируемого заголовка. Например: Host, User-Agent, X-Forwarded-For, Strict-Transport-Security и т.п.
       • append — добавить строку к текущему значению заголовка.
       • replace — полностью заменить текущее значение заголовка.
       • remove — удалить заголовок. При этом будет удалено не только значение заголовка, но и сам заголовок. Возможные значения: true или false.

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

     • route_options — (опционально) дополнительные параметры виртуального хоста:

       • security_profile_id — идентификатор профиля безопасности. Профиль безопасности позволяет настроить фильтрацию входящих запросов, подключить WAF и установить лимиты на количество запросов для защиты от вредоносной активности. Подробнее см. в разделе Профили безопасности.

   Более подробную информацию о параметрах используемых ресурсов в Terraform см. в документации провайдера:

   • Ресурс yandex_alb_http_router.
   • Ресурс yandex_alb_virtual_host.

2. Создайте ресурсы

   1. В терминале перейдите в папку, где вы отредактировали конфигурационный файл.

   2. Проверьте корректность конфигурационного файла с помощью команды:

      terraform validate
      

      Если конфигурация является корректной, появится сообщение:

      Success! The configuration is valid.
      

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

      terraform plan
      

      В терминале будет выведен список ресурсов с параметрами. На этом этапе изменения не будут внесены. Если в конфигурации есть ошибки, Terraform на них укажет.

   4. Примените изменения конфигурации:

      terraform apply
      

   5. Подтвердите изменения: введите в терминале слово yes и нажмите Enter.

   Terraform создаст все требуемые ресурсы. Проверить появление ресурсов и их настройки можно в консоли управления или с помощью команды CLI:

   yc alb http-router get <имя_HTTP-роутера>
   

   Ограничения по времени

   Провайдер Terraform ограничивает время на выполнение операций с HTTP-роутерами и виртуальными хостами Application Load Balancer 10 минутами.

   Операции, которые длятся дольше указанного времени, прерываются.

   Как изменить эти ограничения?

   Добавьте к описанию HTTP-роутера и виртуального хоста блоки timeouts (ресурсы yandex_alb_http_router и yandex_alb_virtual_host соответственно).

   Пример:

   resource "yandex_alb_http_router" "<имя_роутера>" {
     ...
     timeouts {
       create = "60m"
       update = "60m"
       delete = "60m"
     }
   }
   

Воспользуйтесь методом REST API create для ресурса HttpRouter или вызовом gRPC API HttpRouterService/Create.