Skip to content
Kong Docs are moving soon! Our docs are migrating to a new home. You'll be automatically redirected to the new site in the future. In the meantime, view this page on the new site!
Kong Logo | Kong Docs Logo
  • Docs
    • Explore the API Specs
      View all API Specs View all API Specs View all API Specs arrow image
    • Documentation
      API Specs
      Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong AI Gateway
      Multi-LLM AI Gateway for GenAI infrastructure
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Kong Gateway Operator
      Manage your Kong deployments on Kubernetes using YAML Manifests
      Insomnia
      Collaborative API development platform
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      AI's icon
      AI
      Govern, secure, and control AI traffic with multi-LLM AI Gateway plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Mesh
2.4.x
  • Home icon
  • Kong Mesh
  • Policies
  • Virtual Outbound
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Kong AI Gateway
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • dev
  • 2.10.x (latest)
  • 2.9.x
  • 2.8.x
  • 2.7.x (LTS)
  • 2.6.x
  • 2.5.x
  • 2.4.x
  • 2.3.x
  • 2.2.x
  • Introduction
    • About service meshes
    • Overview of Kong Mesh
    • How Kong Mesh works
    • Architecture
    • Stages of software availability
    • Version support policy
    • Mesh requirements
    • Release notes
  • Getting Started
  • Kong Mesh in Production
    • Overview
    • Deployment topologies
      • Overview
      • Standalone deployment
      • Multi-zone deployment
    • Install kumactl
    • Use Kong Mesh
    • Control plane deployment
      • Kong Mesh license
      • Deploy a standalone control plane
      • Deploy a multi-zone global control plane
      • Zone Ingress
      • Zone Egress
      • Configure zone proxy authentication
      • Control plane configuration reference
      • Systemd
      • Kubernetes
    • Create multiple service meshes in a cluster
    • Data plane configuration
      • Data plane proxy
      • Configure the data plane on Kubernetes
      • Configure the data plane on Universal
      • Configure the Kong Mesh CNI
      • Configure transparent proxying
      • IPv6 support
    • Secure your deployment
      • Manage secrets
      • Authentication with the API server
      • Authentication with the data plane proxy
      • Configure data plane proxy membership
      • Secure access across services
      • Kong Mesh RBAC
      • FIPS support
    • Kong Mesh user interface
    • Upgrades and tuning
      • Upgrade Kong Mesh
      • Performance fine-tuning
  • Deploy
    • Explore Kong Mesh with the Kubernetes demo app
    • Explore Kong Mesh with the Universal demo app
  • Explore
    • Gateway
      • Delegated
      • Builtin
    • CLI
      • kumactl
    • Observability
      • Demo setup
      • Control plane metrics
      • Configuring Prometheus
      • Configuring Grafana
      • Configuring Datadog
      • Observability in multi-zone
    • Inspect API
      • Matched policies
      • Affected data plane proxies
      • Envoy proxy configuration
    • Kubernetes Gateway API
      • Installation
      • Gateways
      • TLS termination
      • Customization
      • Multi-mesh
      • Multi-zone
      • GAMMA
      • How it works
  • Networking
    • Service Discovery
    • DNS
      • How it works
      • Installation
      • Configuration
      • Usage
    • Non-mesh traffic
      • Incoming
      • Outgoing
    • Transparent Proxying
  • Monitor & manage
    • Dataplane Health
      • Circuit Breaker Policy
      • Kubernetes and Universal Service Probes
      • Health Check Policy
    • Control Plane Configuration
      • Modifying the configuration
      • Inspecting the configuration
      • Store
  • Policies
    • Introduction
    • General notes about Kong Mesh policies
    • Applying Policies
    • How Kong Mesh chooses the right policy to apply
    • Understanding TargetRef policies
    • Protocol support in Kong Mesh
    • Mutual TLS
      • Usage of "builtin" CA
      • Usage of "provided" CA
      • Permissive mTLS
      • Certificate Rotation
    • Traffic Permissions
      • Usage
      • Access to External Services
    • Traffic Route
      • Usage
    • Traffic Metrics
      • Expose metrics from data plane proxies
      • Expose metrics from applications
      • Override Prometheus settings per data plane proxy
      • Filter Envoy metrics
      • Secure data plane proxy metrics
    • Traffic Trace
      • Add a tracing backend to the mesh
      • Add TrafficTrace resource
    • Traffic Log
      • Add a logging backend
      • Add a TrafficLog resource
      • Logging external services
      • Builtin Gateway support
      • Access Log Format
    • Locality-aware Load Balancing
      • Enabling locality-aware load balancing
    • Fault Injection
      • Usage
      • Matching
    • Health Check
      • Usage
      • Matching
    • Circuit Breaker
      • Usage
      • Matching
      • Builtin Gateway support
      • Non-mesh traffic
    • External Service
      • Usage
      • Builtin Gateway support
    • Retry
      • Usage
      • Matching
      • Builtin Gateway support
    • Timeout
      • Usage
      • Configuration
      • Default general-purpose Timeout policy
      • Matching
      • Builtin Gateway support
      • Inbound timeouts
      • Non-mesh traffic
    • Rate Limit
      • Usage
      • Matching destinations
      • Builtin Gateway support
    • Virtual Outbound
      • Examples
    • MeshGateway
      • TLS Termination
    • MeshGatewayRoute
      • Listener tags
      • Matching
      • Filters
      • Reference
    • MeshGatewayInstance
    • Service Health Probes
      • Kubernetes
      • Universal probes
    • MeshAccessLog (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshCircuitBreaker (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshFaultInjection (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshHealthCheck (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshHTTPRoute (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
      • Merging
    • MeshProxyPatch (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
      • Merging
    • MeshRateLimit (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshRetry (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshTCPRoute (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
      • Route policies with different types targeting the same destination
    • MeshTimeout (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshTrace (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshTrafficPermission (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • MeshLoadBalancingStrategy (Beta)
      • TargetRef support matrix
      • Configuration
      • Examples
    • OPA policy
    • MeshOPA (beta)
    • MeshGlobalRateLimit (beta)
  • Enterprise Features
    • Overview
    • HashiCorp Vault CA
    • Amazon ACM Private CA
    • cert-manager Private CA
    • OPA policy support
    • MeshOPA (beta)
    • Multi-zone authentication
    • FIPS support
    • Certificate Authority rotation
    • Role-Based Access Control
    • UBI Images
    • Windows Support
    • ECS Support
    • Auditing
    • MeshGlobalRateLimit (beta)
  • Reference
    • HTTP API
    • Kubernetes annotations and labels
    • Kuma data collection
    • Control plane configuration reference
    • Envoy proxy template
  • Community
    • Contribute to Kuma
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Examples
    • Same as the default DNS
    • One hostname per version
    • Custom tag to define the hostname and port
    • One hostname per instance
  • All options
You are browsing documentation for an older version. See the latest documentation here.

Virtual Outbound

This policy lets you customize hostnames and ports for communicating with data plane proxies.

Possible use cases are:

  1. Preserving hostnames when migrating to service mesh.
  2. Providing multiple hostnames for reaching the same service, for example when renaming or for usability.
  3. Providing specific routes, for example to reach a specific pod in a service with StatefulSets on Kubernetes, or to add a URL to reach a specific version of a service.
  4. Expose multiple inbounds on different ports.

Limitations:

  • When duplicate (hostname, port) combinations are detected, the virtual outbound with the highest priority takes over. For more information, see the documentation on how Kong Mesh chooses the right policy. All duplicate instances are logged.

conf.host and conf.port are processed as go text templates with a key-value pair derived from conf.parameters.

conf.selectors are used to specify which proxies this policy applies to.

For example a proxy with this definition:

type: Dataplane
mesh: default
name: backend-1
networking:
  address: 192.168.0.2
inbound:
  - port: 9000
    servicePort: 6379
    tags:
      kuma.io/service: backend
      version: v1
      port: 1800

and a virtual outbound with this definition:

Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: VirtualOutbound
mesh: default
metadata:
  name: test
spec:
  selectors:
    - match:
        kuma.io/service: "*"
  conf:
    host: "{{.v}}.{{.service}}.mesh"
    port: "{{.port}}"
    parameters:
      - name: service
        tagKey: "kuma.io/service"
      - name: port
        tagKey: "k8s.kuma.io/service-port"
      - name: v
        tagKey: version
type: VirtualOutbound
mesh: default
name: test
selectors:
  - match:
      kuma.io/service: "*"
conf:
  host: "{{.v}}.{{.service}}.mesh"
  port: "{{.port}}"
  parameters:
    - name: service
      tagKey: "kuma.io/service"
    - name: port
      tagKey: port
    - name: v
      tagKey: version

produce the hostname: v1.backend.mesh with port: 1800.

Additional Requirements:

  • Transparent proxying must be enabled.
  • Either:
    • Data plane proxy DNS must be enabled.
    • Or, the value of conf.host must end with the value of dns_server.domain, which defaults to .mesh.
  • Parameter names must be alphanumeric. These names are used as Go template keys.
  • Parameter names must be unique. This ensures that each parameter can be referenced unambiguously.
  • Parameter with the kuma.io/service tagKey must be specified even if it is not used in the template. This prevents hostnames from being defined that could span multiple services.

The default value of tagKey is the value of name.

For each virtual outbound, the Kong Mesh control plane processes all data plane proxies that match the selector. It then applies the templates for conf.host and conf.port and assigns a virtual IP address for each hostname.

Examples

The following examples show how to use virtual outbounds for different use cases.

Same as the default DNS

Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: VirtualOutbound
mesh: default
metadata:
    name: default
spec:
    selectors:
      - match:
          kuma.io/service: "*"
    conf:
      host: "{{.service}}.mesh"
      port: "80"
      parameters:
        - name: service
          tagKey: "kuma.io/service"
type: VirtualOutbound
mesh: default
name: default
selectors:
  - match:
      kuma.io/service: "*"
conf:
  host: "{{.service}}.mesh"
  port: "80"
  parameters:
    - name: service
      tagKey: "kuma.io/service"

One hostname per version

Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: VirtualOutbound
mesh: default
metadata:
  name: versioned
spec:
    selectors:
      - match:
          kuma.io/service: "*"
    conf:
      host: "{{.service}}.{{.version}}.mesh"
      port: "80"
      parameters:
        - name: service
          tagKey: "kuma.io/service"
        - name: version
          tagKey: "kuma.io/version"
type: VirtualOutbound
mesh: default
name: versioned
spec:
    selectors:
      - match:
          kuma.io/service: "*"
    conf:
      host: "{{.service}}.{{.version}}.mesh"
      port: "80"
      parameters:
        - name: service
          tagKey: "kuma.io/service"
        - name: version
          tagKey: "kuma.io/version"

Custom tag to define the hostname and port

Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: VirtualOutbound
mesh: default
metadata:
  name: host-port
spec:
    selectors:
      - match:
          kuma.io/service: "*"
    conf:
      host: "{{.hostname}}"
      port: "{{.port}}"
      parameters:
        - name: hostname
          tagKey: "my.mesh/hostname"
        - name: port
          tagKey: "my.mesh/port"
type: VirtualOutbound
mesh: default
name: host-port
selectors:
  - match:
      kuma.io/service: "*"
conf:
  host: "{{.hostname}}"
  port: "{{.port}}"
  parameters:
    - name: hostname
      tagKey: "my.mesh/hostname"
    - name: port
      tagKey: "my.mesh/port"
    - name: service

One hostname per instance

Enables reaching specific data plane proxies for a service. Useful for running distributed databases such as Kafka or Zookeeper.

Kubernetes
Universal
apiVersion: kuma.io/v1alpha1
kind: VirtualOutbound
mesh: default
metadata:
  name: instance
spec:
  selectors:
    - match:
        kuma.io/service: "*"
        statefulset.kubernetes.io/pod-name: "*"
  conf:
    host: "{{.svc}}.{{.inst}}.mesh"
    port: "8080"
    parameters:
      - name: "svc"
        tagKey: "kuma.io/service"
      - name: "inst"
        tagKey: "statefulset.kubernetes.io/pod-name"
type: VirtualOutbound
mesh: default
name: default
selectors:
  - match:
      kuma.io/service: "*"
      kuma.io/instance: "*"
conf:
  host: "inst-{{.instance}}.{{.service}}.mesh"
  port: "8080"
  parameters:
    - name: service
      tagKey: "kuma.io/service"
    - name: instance
      tagKey: "kuma.io/instance"

All options

$schema: http://json-schema.org/draft-04/schema#

$ref: #/definitions/VirtualOutbound

definitions

VirtualOutbound

  • ## Virtual Outbound

  • VirtualOutbound defines how to generate hostname ports combination.

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • selectors
      • List of selectors to match dataplanes that this policy applies to
      • Type: array
        • Items
        • $ref: #/definitions/kuma.mesh.v1alpha1.Selector
    • conf
      • Type: object
      • $ref: #/definitions/kuma.mesh.v1alpha1.VirtualOutbound.Conf
      • This schema accepts additional properties.
      • Properties kuma.mesh.v1alpha1.Selector
  • ## Selector

  • Selector defines structure for selecting tags for given dataplane

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • match
      • Tags to match, can be used for both source and destinations
      • Type: object
      • This schema accepts additional properties.
      • Properties kuma.mesh.v1alpha1.VirtualOutbound.Conf
  • ## Conf

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • host
      • Host the gotemplate to generate the hostname from the Parameters map
      • Type: string
    • port
      • Port the gotemplate to generate the port from the Parameters map
      • Type: string
    • parameters
      • Parameters a mapping between tag keys and template parameter key. This must always contain at least kuma.io/service
      • Type: array
        • Items
        • $ref: #/definitions/kuma.mesh.v1alpha1.VirtualOutbound.Conf.TemplateParameter kuma.mesh.v1alpha1.VirtualOutbound.Conf.TemplateParameter
  • ## Template Parameter

  • A mapping between a template parameter and a dataplane outbound tag name.

  • Type: object

  • This schema accepts additional properties.

  • Properties

    • name
      • Name the name of the template parameter (must be alphanumeric).
      • Type: string
    • tag_key
      • TagKey the name of the tag in the Kuma outbound (optional if absent it will use Name).
      • Type: string

Generated with json-schema-md-doc Wed May 14 2025 08:42:29 GMT+0000 (Coordinated Universal Time)

Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    Powering the API world

    Increase developer productivity, security, and performance at scale with the unified platform for API management, service mesh, and ingress controller.

    • Products
      • Kong Konnect
      • Kong Gateway Enterprise
      • Kong Gateway
      • Kong Mesh
      • Kong Ingress Controller
      • Kong Insomnia
      • Product Updates
      • Get Started
    • Documentation
      • Kong Konnect Docs
      • Kong Gateway Docs
      • Kong Mesh Docs
      • Kong Insomnia Docs
      • Kong Konnect Plugin Hub
    • Open Source
      • Kong Gateway
      • Kuma
      • Insomnia
      • Kong Community
    • Company
      • About Kong
      • Customers
      • Careers
      • Press
      • Events
      • Contact
  • Terms• Privacy• Trust and Compliance
© Kong Inc. 2025