Creating an HTTP router for gRPC traffic

If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

1. See the description of the CLI command for creating an HTTP router:

   yc alb http-router create --help
   

2. Run this command:

   yc alb http-router create <HTTP_router_name>
   

   Result:

   id: a5dcsselagj4********
   name: <HTTP_router_name>
   folder_id: aoerb349v3h4********
   created_at: "2022-06-16T21:04:59.438292069Z"
   

3. See the description of the CLI command for creating a virtual host:

   yc alb virtual-host create --help
   

4. Create a virtual host by specifying its name and these settings:

   yc alb virtual-host create <virtual_host_name> \
     --http-router-name <HTTP_router_name> \
     --authority <domain_1>,<domain_2>,...,<domain_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 <security_profile_ID>
   

   Where:

   • --http-router-name: HTTP router name.

     Instead of the HTTP router name, you can provide its ID in the --http-router-id parameter.

   • --authority: List of domains for the Host header (HTTP/1.1) or the authority pseudo-header (HTTP/2) associated with this virtual host, comma-separated. You can use wildcards, e.g., *.foo.com or *-bar.foo.com. For gRPC traffic, you may specify the load balancer's IP address.

     This is an optional parameter. If not specified, all traffic will be routed to this virtual host.

   • --modify-request-header: Request HTTP header modification settings in <property>=<value> format. Available properties:

     • name: Modified header name, e.g., Host, User-Agent, X-Forwarded-For, Strict-Transport-Security, etc.
     • append: Add a row to the current header value.
     • replace: Completely replace the current header value.
     • rename: Change the header name. The header value will not change.
     • remove: Delete the header. Both the header value and the header itself will be removed.

     To modify multiple HTTP headers in a request, include --modify-request-header as many times as needed.

     This is an optional parameter; if omitted, request headers go to the backend unchanged.

   • --modify-response-header: Response HTTP header modification settings in <property>=<value> format. Available properties:

     • name: Modified header name, e.g., Host, User-Agent, X-Forwarded-For, Strict-Transport-Security, etc.
     • append: Add a row to the current header value.
     • replace: Completely replace the current header value.
     • rename: Change the header name. The header value will not change.
     • remove: Delete the header. Both the header value and the header itself will be removed.

     To modify multiple HTTP headers in a response, include --modify-response-header as many times as needed.

     This is an optional parameter; if omitted, response headers go to the client unchanged.

   • --rate-limit: Request rate limit. Available properties:

     • rps or rpm: Number of incoming requests per second or per minute.
     • all-requests: Limits all incoming requests.
     • requests-per-ip: Limits requests per client IP address.

     You can configure only one type of rate limit per virtual host, either all-requests or requests-per-ip.

     This is an optional parameter; if not specified, no rate limiting is applied.

   • --security-profile-id: Yandex Smart Web Security security profile ID. A security profile allows you to filter incoming requests, enable WAF, and set limits on the number of requests for protection against malicious activities. For more information, see Security profiles. This is an optional parameter.

   Result:

   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. See the description of the CLI command for adding a route to the end of the virtual host's route list:

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

6. Add the route by specifying its name and additional parameters:

   yc alb virtual-host append-grpc-route <route_name> \
     --http-router-name <HTTP_router_name> \
     --virtual-host-name <virtual_host_name> \
     --exact-fqmn-match <full_FQMN> \
     --prefix-fqmn-match <FQMN_prefix> \
     --regex-fqmn-match <regular_expression> \
     --backend-group-name <backend_group_name> \
     --request-max-timeout <request_timeout>s \
     --request-idle-timeout <request_idle_timeout>s \
     --rate-limit rps=<request_limit>,requests-per-ip \
     --disable-security-profile
   

   Where:

   • --http-router-name: Name of the HTTPS router you are creating the route in.

     Instead of the HTTP router name, you can provide its ID in the --http-router-id parameter.

   • --virtual-host-name: Name of the virtual host you are creating the route in.

   • FQMN-based routing condition parameters:

     • --exact-fqmn-match: Route requests with the same FQMN as the specified one.
     • --prefix-fqmn-match: Route requests whose FQMN starts with the specified prefix. For example, you can specify the first word of the service name: /helloworld.
     • --regex-fqmn-match: Route requests whose FQMN matches the specified RE2 regular expression. For example: \/[a-z]{10}[0-9]{3}.

     Warning

     The FQMN must start with a slash / and contain a part of the service name where your procedure call is redirected.

     Note

     The --exact-fqmn-match, --prefix-fqmn-match, and --regex-fqmn-match parameters are mutually exclusive: you can use only one of them.

   • --backend-group-name: Name of the backend group located in the same folder as the HTTP router and virtual host for which you are creating the new route.

     Instead of the backend group name, you can provide its ID in the --backend-group-id parameter.

   • --request-max-timeout: Maximum connection time. You can specify a shorter timeout in the grpc-timeout request HTTP header.

   • --request-idle-timeout: Maximum connection idle time in seconds.

   • --rate-limit: Request rate limit. Available properties:

     • rps or rpm: Number of incoming requests per second or per minute.
     • all-requests: Limits all incoming requests.
     • requests-per-ip: Limits requests per client IP address.

     You can configure only one type of rate limit per route, either all-requests or requests-per-ip.

     This is an optional parameter; if not specified, no rate limiting is applied.

   • --disable-security-profile: Parameter that disables the use of the virtual host’s Yandex Smart Web Security profile for the route. A security profile allows you to filter incoming requests, enable WAF, and set limits on the number of requests for protection against malicious activity. For more information, see Security profiles. This is an optional parameter. By default, the security profile associated with a virtual host applies to all routes you create.

   Result:

   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"
   

   For more details about the yc alb virtual-host append-grpc-route command, see the CLI reference.

With Terraform, you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.

Terraform is distributed under the Business Source License. The Yandex Cloud provider for Terraform is distributed under the MPL-2.0 license.

For more information about the provider resources, see the relevant documentation on the Terraform website or its mirror.

If you do not have Terraform yet, install it and configure the Yandex Cloud provider.

1. In the configuration file, specify your HTTP router and virtual host settings:

   resource "yandex_alb_http_router" "tf-router" {
     name          = "<HTTP_router_name>"
     labels        = {
       tf-label    = "tf-label-value"
       empty-label = ""
     }
   }
   
   resource "yandex_alb_virtual_host" "my-virtual-host" {
     name           = "<virtual_host_name>"
     http_router_id = yandex_alb_http_router.tf-router.id
   
     rate_limit {
       all_requests {
         per_second = <requests_per_second>
         # or per_minute = <requests_per_minute>
       }
       requests_per_ip {
         per_second = <requests_per_second>
         # or per_minute = <requests_per_minute>
       }
     }
   
     route {
       name                      = "<route_name>"
       disable_security_profile  = true|false
   
       grpc_route {
         grpc_match {
           fqmn {
             prefix = "/<request_FQMN_prefix>"
             # or exact = "<request_FQMN>"
             # or regex = "<regular_expression>"
           }
         }
   
         grpc_route_action {
           backend_group_id  = "<backend_group_ID>"
           host_rewrite      = "<Host_header_value>"
           max_timeout       = "<connection_timeout>s"
           idle_timeout      = "<idle_timeout>s"
           rate_limit {
             all_requests {
               per_second = <requests_per_second>
               # or per_minute = <requests_per_minute>
             }
             requests_per_ip {
               per_second = <requests_per_second>
               # or per_minute = <requests_per_minute>
             }
           }
         }
       }
     }
   
     authority        = ["<domain_1>","<domain_2>",...,"<domain_n>"]
   
     modify_request_headers {
       name           = "<header_name>"
       append         = "<string_added_to_header_content>"
       # or replace  = "<new_header_content>"
       # or remove   = true|false
     }
   
     modify_response_headers {
       name           = "<header_name>"
       append         = "<string_added_to_header_content>"
       # or replace  = "<new_header_content>"
       # or remove   = true|false
     }
   
     route_options {
       security_profile_id = "<security_profile_ID>"
     }
   }
   

   Where:

   • yandex_alb_http_router: HTTP router description.

     • name: HTTP router name. Follow these naming requirements:

       • It must be from 2 to 63 characters long.
       • It can only contain lowercase Latin letters, numbers, and hyphens.
       • It must start with a letter and cannot end with a hyphen.

     • labels: HTTP router labels. Specify a key-value pair.

   • yandex_alb_virtual_host: Virtual host description:

     • name: Virtual host name. Follow these naming requirements:

       • It must be from 2 to 63 characters long.
       • It can only contain lowercase Latin letters, numbers, and hyphens.
       • It must start with a letter and cannot end with a hyphen.

     • http_router_id: HTTP router ID.

     • rate_limit: Request rate limit for the entire virtual host (optional).

       • all_requests: Limit on all requests per second or per minute (optional):

         • per_second: Maximum number of incoming requests to the virtual host per second.
         • per_minute: Maximum number of incoming requests to the virtual host per minute.

         The per_second, and per_minute parameters are mutually exclusive: you can use only one of them.

       • requests_per_ip: Additionally limits requests for each IP address per second or per minute (optional):

         • per_second: Maximum number of incoming requests from a single IP address to the virtual host per second.
         • per_minute: Maximum number of incoming requests from a single IP address to the virtual host per minute.

         The per_second, and per_minute parameters are mutually exclusive: you can use only one of them.

     • route: Virtual host route description:

       • name: Route name.
       • disable_security_profile: Disabling the Yandex Smart Web Security security profile (optional). The possible values are true (the profile is disabled) or false (the profile is enabled). The default value is false: the security profile is enabled.

       • grpc_route: Route description for gRPC traffic:

         • grpc_match.fqmn: Parameter for filtering incoming gRPC requests by FQMN (optional):

           • exact: Route requests with the same FQMN as the specified one.
           • prefix: Route requests whose FQMN starts with the specified prefix. For example, you can specify the first word of the service name: /helloworld.
           • regex: Route requests whose FQMN matches the specified RE2 regular expression. For example: \/[a-z]{10}[0-9]{3}.

           The exact, prefix, and regex parameters are mutually exclusive: you can use only one of them.

         • grpc_route_action: Action applied to gRPC traffic.

           • backend_group_id: ID of the backend group located in the same folder as the new route's HTTP router and virtual host.
           • host_rewrite: Replacing the Host header in the request with the specified value (optional). You can specify auto_host_rewrite instead of host_rewrite, in which case the Host header in the request will be automatically replaced with the target VM address.
           • --request-max-timeout: Maximum request timeout in seconds (optional). You can specify a shorter timeout in the grpc-timeout request HTTP header. The default value is 60 seconds.
           • idle_timeout: Maximum connection idle timeout (keep-alive time) (optional). If not specified, the idle connection will be terminated immediately.

           • rate_limit: Limits the number of requests per unit of time (optional):

             • all_requests: Limits all incoming requests (optional):

               • per_second: Maximum number of incoming requests to a route per second.
               • per_minute: Maximum number of incoming requests to a route per minute.

               The per_second, and per_minute parameters are mutually exclusive: you can use only one of them.

             • requests_per_ip: Limits incoming requests from a single IP address (optional):

               • per_second: Maximum number of incoming requests to a route from a single IP address per second.
               • per_minute: Maximum number of incoming requests to a route from a single IP address per minute.

               The per_second, and per_minute parameters are mutually exclusive: you can use only one of them.

     • authority: HTTP/1.1 Host (HTTP/2 authority) header domains associated with this virtual host. You can use wildcards, e.g., *.foo.com or *-bar.foo.com. For gRPC traffic, you may specify * or the the load balancer's IP address.

       This is an optional parameter. If not specified, all traffic will be routed to this virtual host.

     • modify_request_headers: HTTP request header modification settings. Possible parameters:

       • name: Modified header name, e.g., Host, User-Agent, X-Forwarded-For, Strict-Transport-Security, etc.
       • append: Add a row to the current header value.
       • replace: Completely replace the current header value.
       • remove: Delete the header. Both the header value and the header itself will be removed. The possible values are true or false.

       This is an optional parameter; if omitted, request headers go to the backend unchanged.

     • modify_response_headers: HTTP response header modification settings. Possible parameters:

       • name: Modified header name, e.g., Host, User-Agent, X-Forwarded-For, Strict-Transport-Security, etc.
       • append: Add a row to the current header value.
       • replace: Completely replace the current header value.
       • remove: Delete the header. Both the header value and the header itself will be removed. The possible values are true or false.

       This is an optional parameter; if omitted, response headers go to the client unchanged.

     • route_options: Additional virtual host parameters (optional):

       • security_profile_id: Security profile ID. A security profile allows you to filter incoming requests, enable WAF, and set limits on the number of requests for protection against malicious activity. For more information, see Security profiles.

   Learn more about the properties of Terraform resources in the relevant Terraform guides:

   • yandex_alb_http_router resource
   • yandex_alb_virtual_host resource

2. Create the resources

   1. In the terminal, go to the directory where you edited the configuration file.

   2. Make sure the configuration file is correct using this command:

      terraform validate
      

      If the configuration is correct, you will get this message:

      Success! The configuration is valid.
      

   3. Run this command:

      terraform plan
      

      You will see a detailed list of resources. No changes will be made at this step. If the configuration contains any errors, Terraform will show them.

   4. Apply the changes:

      terraform apply
      

   5. Type yes and press Enter to confirm the changes.

   Terraform will create all the required resources. You can check your new resources and their settings in the management console or using this CLI command:

   yc alb http-router get <HTTP_router_name>
   

   Timeouts

   The Terraform provider limits the execution time for operations with Application Load Balancer HTTP routers and virtual hosts to 10 minutes.

   Operations in excess of this time will be interrupted.

   How do I modify these limits?

   Add the timeouts section to the descriptions of the HTTP router and virtual host (the yandex_alb_http_router and yandex_alb_virtual_host resources, respectively).

   Here is an example:

   resource "yandex_alb_http_router" "<router_name>" {
     ...
     timeouts {
       create = "60m"
       update = "60m"
       delete = "60m"
     }
   }
   

Use the create REST API method for the HttpRouter resource or the HttpRouterService/Create gRPC API call.