MultiKeyListener resource¶

A multi-key listener binds a single local host and port to multiple routing keys in remote sites. Use a multi-key listener when you want one service endpoint to aggregate traffic from multiple connectors.

Unlike a standard listener which maps to a single routing key, a MultiKeyListener can route to multiple connectors using either priority-based or weighted distribution strategies.

Examples¶

A weighted multi-key listener that distributes traffic evenly across multiple backends:

apiVersion: skupper.io/v2alpha1
kind: MultiKeyListener
metadata:
  name: mkl-backend
spec:
  host: mkl-backend
  port: 9092
  strategy:
    weighted:
      routingKeys:
        east-backend: 1
        west-backend: 1

A priority-based multi-key listener that prefers one routing key and falls back to another if unavailable:

apiVersion: skupper.io/v2alpha1
kind: MultiKeyListener
metadata:
  name: mkl-backend-priority
spec:
  host: mkl-backend-priority
  port: 9095
  strategy:
    priority:
      routingKeys:
        - east-backend-http
        - west-backend-http

Metadata properties¶

name

string

required

The name of the resource.

See also	Kubernetes object names

namespace

string

The namespace of the resource.

See also	Platform concept, Kubernetes namespaces

Spec properties¶

host

string

required

The hostname or IP address of the local listener. Clients at this site use the listener host and port to establish connections to the remote service.

Updatable	True

port

integer

required

The port of the local listener. Clients at this site use the listener host and port to establish connections to the remote service.

Updatable	True

strategy

object

required

Strategy for routing traffic from the local listener endpoint to one or more connector instances by routing key. Must specify exactly one of: - `priority`: Route to routing keys in priority order (failover) - `weighted`: Distribute traffic across routing keys by weight (load balancing) The strategy operates independently of link costs and provides predictable, client-side traffic control. If multiple multi-key listeners reference the same routing keys, each listener assigns connections autonomously without coordination. **Note:** The strategy is immutable and cannot be changed after creation.

observer

string

advanced

Controls how the listener inspects network traffic for application-level protocol information. When unset or set to `auto`, the listener inspects traffic to detect known application protocols and produces telemetry events. Set to a specific protocol to restrict inspection, or `none` to disable inspection and reduce overhead.

Choices

`auto`	Automatically detect application protocols and produce telemetry
`none`	Disable protocol inspection to reduce overhead
`http1`	Restrict inspection to HTTP/1 protocol only
`http2`	Restrict inspection to HTTP/2 protocol only

tlsCredentials

string

advanced

The name of a bundle of TLS certificates used for secure client-to-router communication. The bundle contains the server certificate and key. It optionally includes the trusted client certificate (usually a CA) for mutual TLS. On Kubernetes, the value is the name of a Secret in the current namespace. On Docker, Podman, and Linux, the value is the name of a directory under `input/certs/` in the current namespace.

See also	Kubernetes TLS secrets

requireClientCert

boolean

advanced

Indicates that clients must present valid certificates to the listener to connect. Requires `tlsCredentials` to be configured with a trusted CA certificate.

Default	False

settings

object

advanced

A map containing additional settings. Each map entry has a string name and a string value. **Note:** In general, we recommend not changing settings from their default values.

Status properties¶

status

string

The current state of the resource. - `Pending`: The resource is being processed. - `Error`: There was an error processing the resource. See `message` for more information. - `Ready`: The resource is ready to use.

message

string

A human-readable status message. Error messages are reported here.

hasDestination

boolean

True if there is at least one connector in the network with a routing key matched by the strategy.

Default	False

strategy

object

Current state of the routing strategy, including which routing keys are reachable. Contains either `priority` or `weighted` status depending on the configured strategy.

conditions

array

advanced

A set of named conditions describing the current state of the resource. - `Configured`: The multi-key listener configuration has been applied to the router. - `Operational`: There is at least one connector corresponding to the multi-key listener strategy. - `Ready`: The multi-key listener is ready to use. All other conditions are true.

See also	Kubernetes conditions