Skip to main content
Version: 13.x (Current)

Create Listeners

Listeners Management​

From the Design area you can manage your Listeners and control where your Endpoints are exposed. This means that you can map Endpoints to different Listeners, which will make them available on different exposed domains.

info

Currently only Projects configured with an Envoy API Gateway can access the Listeners feature.

What is a Listener​

A Listener is a logical entity configured on your API Gateway that checks for incoming connection requests directed to your Project namespace.
Each listener is mapped to a single port and defines rules to route incoming requests from external clients to a resource in your namespace, such as a specific microservice, exposed through endpoints.

This page describes the features of a Listener and how to configure them from the Listeners section of the Design area in Console.

Create a Listener​

There are three main steps needed to make an Endpoint reachable from outside the Console:

  • Create the new Listener resource
  • Expose the Endpoint on the Listener
  • Configure the Kubernetes Ingress Controller to make the new exposed port reachable

Continue reading through the following sections for a more detailed guide on how to perform them.

Defining the Listener​

To create a new listener, just click the Add Listener button and specify its name and port. Both fields must be unique in the Project.

info

The configured port field is the external envoy listener port. The incoming traffic on the Listener port is directed to port 80 within the pods.
When exposing a Microservice Endpoint via Listeners you must ensure that the 80 port is configured on the Container Ports of the Microservice.

The graph below shows the underneath flow when a request enters the k8s namespace (eg: calling GET https://test.my-domain.com/api/my-api) towards the microservice exposed endpoint (eg: GET https://my-service:3000/my-api)

graph LR A[Client] --> B{Ingress Controller \n if configured \n eg: test.my-domain.com} B --> C{Envoy Listener Port \n eg: 8080} C --> D{Envoy Route Port \n port: 80} D --> E{Pod Container Port \n eg: 80} E --> F{Microservice Internal Port \n eg: 3000}

Optionally, during listener creation, you can define whether to:

  • set the listener as default, so that it is pre-selected when creating new endpoints. This comes in handy if you think you will use the listener to expose many new endpoints. You can always de-select it if needed.
  • expose all existing endpoints on that listener

create-listener

Creating a new Listener means opening the relative container port on the API Gateway too. This step is automated and in fact you can find the new port under the Container Ports section of the API Gateway.

caution

Container Ports associated to Listeners cannot be deleted. To delete them firstly delete the Listener and then you can delete the port.

listeners-api-gateway-container-ports

Exposing an Endpoint on the Listener​

There are two ways to expose an Endpoint on the Listener:

  • selecting the desired Listener from the Listener Settings section within the Endpoint detail page of the Project
  • selecting the desired Listener from the specific Endpoints table within Listeners section

Endpoints list with their listener relations​

The Endpoints tab contains a table that provides an overview of which Endpoint is exposed by which Listeners.
It is possible to edit this configuration by simply selecting the desired Listener for the desired Endpoint.

listeners-api-gateway-container-ports

Configure the Kubernetes Ingress Controller​

In order to receive incoming requests from the newly exposed API Gateway port, it is required to configure the Kubernetes Ingress Controller to make the exposed port reachable.

info

For example, if your Kubernetes cluster is configured to use Traefik as Ingress Controller provider, you may need to define a new IngressRoute.

For more details on configuring a new IngressRoute, please refer to this guide.

Edit a Listener​

From the Listeners section of the Design area of the Console it is possible to update settings of a Listener.

Changes made to the port of the Listener will be reflected on the Container Ports of the API Gateway too.
This means that changing the port of a Listener will also enable the relative port on the API Gateway. The old port of the API Gateway stays enabled and it is up to the user to disable it if needed.

danger

Make sure to modify the Kubernetes Ingress Controller accordingly.

edit-listener

Delete a Listener​

To delete a listener just click on the delete action.

danger

Be aware that Endpoints that are only exposed by the Listener you are deleting, will be deleted as well.

delete-listener