Virtual Outbound
This policy lets you customize hostnames and ports for communicating with data plane proxies.
Possible use cases are:
- Preserving hostnames when migrating to service mesh.
- Providing multiple hostnames for reaching the same service, for example when renaming or for usability.
- 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.
- 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:
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
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 ofdns_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
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"
One hostname per version
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"
Custom tag to define the hostname and port
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"
One hostname per instance
Enables reaching specific data plane proxies for a service. Useful for running distributed databases such as Kafka or Zookeeper.
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"
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
- selectors
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
- match
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
- Parameters a mapping between tag keys and template parameter key. This must always contain at least
- host
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
- name
Generated with json-schema-md-doc