Yandex Cloud
Search
Contact UsGet started
  • Pricing
  • Customer Stories
  • Documentation
  • Blog
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • AI Studio
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Start testing with double trial credits
    • Cloud credits to scale your IT product
    • Gateway to Russia
    • Cloud for Startups
    • Center for Technologies and Society
    • Yandex Cloud Partner program
  • Pricing
  • Customer Stories
  • Documentation
  • Blog
© 2025 Direct Cursus Technology L.L.C.
Service page
Yandex Network Load Balancer
Documentation
Yandex Network Load Balancer
  • Getting started
    • All guides
      • Information about current network load balancers
      • Creating a load balancer
      • Creating an internal load balancer
      • Stopping and starting a load balancer
      • Changing load balancer settings
      • Moving a VM to a target group in a new availability zone
      • Deleting a load balancer
      • Checking target health statuses
      • Adding a listener
      • Deleting a listener
    • Viewing service resource operations
  • Access management
  • Pricing policy
  • Terraform reference
  • Monitoring metrics
  • Audit Trails events
  • Release notes
  • FAQ

In this article:

  • Examples
  • Adding a listener to a network load balancer
  1. Step-by-step guides
  2. Network load balancers
  3. Adding a listener

Adding a listener to a network load balancer

Written by
Yandex Cloud
Updated at July 14, 2025
  • Examples
    • Adding a listener to a network load balancer
Management console
CLI
Terraform
API

To add a listener to a network load balancer:

  1. In the management console, select the folder where you need to add a listener to a load balancer.

  2. In the list of services, select Network Load Balancer.

  3. Next to the load balancer to add a listener to, click and select Add listener.

  4. In the window that opens, specify these listener settings:

    • Name.

    • Protocol: TCP or UDP.

      Note

      By default, the listener uses TCP. To use UDP, contact technical support.

    • Port where the listener will listen for incoming traffic. The possible values range from 1 to 32767.

    • Target port to which the load balancer will redirect traffic. The possible values range from 1 to 32767.

    • Click Add.

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.

To add a listener to a network load balancer, run this command:

yc load-balancer network-load-balancer add-listener <load_balancer_name_or_ID> \
   --listener name=<listener_name>,`
             `port=<port>,`
             `target-port=<target_port>,`
             `protocol=<protocol>,`
             `external-address=<external_IP_address>,`
             `external-ip-version=<IP_address_version>

Where:

  • --listener: Listener settings:
    • name: Listener name.
    • port: Port on which the load balancer will listen to incoming traffic. The possible values range from 1 to 32767.
    • target-port: Port to which the load balancer will redirect traffic. The possible values range from 1 to 32767.
    • protocol: Protocol the listener will use, tcp or udp.
    • external-address: External IP address of the listener.
    • external-ip-version: External IP address version, ipv4 or ipv6.

You can get the load balancer ID and name with the list of network load balancers in the folder.

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. Open the Terraform configuration file and add the listener section to the network load balancer description:

    resource "yandex_lb_network_load_balancer" "foo" {
      name = "<load_balancer_name>"
      ...
      listener {
        name = "<listener_name>"
        port = <port_number>
        external_address_spec {
          ip_version = "<IP_address_version>"
        }
      }
      ...
    }
    

    Where:

    • name: Name of the network load balancer.
    • listener: Listener settings:
      • name: Listener name.
      • port: Port number (ranging from 1 to 32767) on which the load balancer will listen to incoming traffic.
      • external_address_spec: Specification of the listener for the external load balancer settings:
        • ip_version: External IP address specification. Specify the IP address version, ipv4 or ipv6. The default value is ipv4.

    For more information about yandex_lb_network_load_balancer settings, see this Terraform article.

  2. Make sure the settings are correct.

    1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

    2. Run this command:

      terraform validate
      

      Terraform will show any errors found in your configuration files.

  3. Add a listener.

    1. Run this command to view the planned changes:

      terraform plan
      

      If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

    2. If everything looks correct, apply the changes:

      1. Run this command:

        terraform apply
        
      2. Confirm updating the resources.

      3. Wait for the operation to complete.

To add a listener to a network load balancer, use the addListener REST API method for the NetworkLoadBalancer resource or the NetworkLoadBalancerService/AddListener gRPC API call.

ExamplesExamples

Adding a listener to a network load balancerAdding a listener to a network load balancer

Add a listener with the following test settings to test-load-balancer:

  • Name: test-listener
  • Port: 80
  • Target port: 81
  • Protocol: TCP
  • IP address version: ipv4
CLI
Terraform
API

Run this command:

yc load-balancer network-load-balancer add-listener test-load-balancer \
   --listener name=test-listener,`
             `port=80,`
             `target-port=81,`
             `protocol=tcp,`
             `external-ip-version=ipv4
  1. Open the Terraform configuration file and add the listener section to the network load balancer description:

    resource "yandex_lb_network_load_balancer" "foo" {
      name = "test-load-balancer"
      listener {
        name        = "test-listener"
        port        = 80
        target_port = 81
        protocol    = "tcp"
        external_address_spec {
          ip_version = "ipv4"
        }
      }
    }
    

    For more information about the resources you can create with Terraform, see this article.

  2. Make sure the settings are correct.

    1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

    2. Run this command:

      terraform validate
      

      Terraform will show any errors found in your configuration files.

  3. Create a network load balancer.

    1. Run this command to view the planned changes:

      terraform plan
      

      If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

    2. If everything looks correct, apply the changes:

      1. Run this command:

        terraform apply
        
      2. Confirm updating the resources.

      3. Wait for the operation to complete.

Use the addListener API method, providing the following in the request body:

{
  "listenerSpec": {
    "name": "test-listener",
    "port": "80",
    "protocol": "TCP",
    "targetPort": "81",
    "externalAddressSpec": {
      "ipVersion": "ipv4"
    }
  }
}

Was the article helpful?

Previous
Checking target health statuses
Next
Deleting a listener
© 2025 Direct Cursus Technology L.L.C.