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:

  • Complex virtual outbounds do not work for cross-zone traffic. This is because only service tags are propagated across zones.
  • When duplicate (hostname, port) combinations are detected, the virtual outbound with the highest priority takes over. For more information, see the documentation on how Kuma 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:

  1. type: Dataplane
  2. mesh: default
  3. name: backend-1
  4. networking:
  5.   address: 192.168.0.2
  6. inbound:
  7.   - port: 9000
  8.     servicePort: 6379
  9.     tags:
  10.       kuma.io/service: backend
  11.       version: v1
  12.       port: 1800

and a virtual outbound with this definition:

  1. type: VirtualOutbound
  2. mesh: default
  3. name: test
  4. selectors:
  5.   - match:
  6.       kuma.io/service: "*"
  7. conf:
  8.   host: "{{.v}}.{{.service}}.mesh"
  9.   port: "{{.port}}"
  10.   parameters:
  11.     - name: service
  12.       tagKey: "kuma.io/service"
  13.     - name: port
  14.       tagKey: port
  15.     - name: v
  16.       tagKey: version

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

Additional requirements:

  • Transparent proxy.
  • Either data plane proxy DNS, or else the value of conf.host must end with the value of dns_server.domain (default value .mesh).
  • name must be alphanumeric. (Used as a go template key).
  • Each value of name must be unique.
  • kuma.io/service must be specified even if it’s unused in the template. (Prevents defining hostnames that spans services).

The default value of tagKey is the value of name.

For each virtual outbound, the Kuma 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

  1. apiVersion: kuma.io/v1alpha1
  2. kind: VirtualOutbound
  3. mesh: default
  4. metadata:
  5.     name: default
  6. spec:
  7.     selectors:
  8.       - match:
  9.           kuma.io/service: "*"
  10.     conf:
  11.       host: "{{.service}}.mesh"
  12.       port: "80"
  13.       parameters:
  14.         - name: service
  15.           tagKey: "kuma.io/service"
  1. type: VirtualOutbound
  2. mesh: default
  3. name: default
  4. selectors:
  5.   - match:
  6.       kuma.io/service: "*"
  7. conf:
  8.   host: "{{.service}}.mesh"
  9.   port: "80"
  10.   parameters:
  11.     - name: service
  12.       tagKey: "kuma.io/service"

One hostname per version

  1. apiVersion: kuma.io/v1alpha1
  2. kind: VirtualOutbound
  3. mesh: default
  4. metadata:
  5.   name: versioned
  6. spec:
  7.     selectors:
  8.       - match:
  9.           kuma.io/service: "*"
  10.     conf:
  11.       host: "{{.service}}.{{.version}}.mesh"
  12.       port: "80"
  13.       parameters:
  14.         - name: service
  15.           tagKey: "kuma.io/service"
  16.         - name: version
  17.           tagKey: "kuma.io/version"
  1. type: VirtualOutbound
  2. mesh: default
  3. name: versioned
  4. spec:
  5.     selectors:
  6.       - match:
  7.           kuma.io/service: "*"
  8.     conf:
  9.       host: "{{.service}}.{{.version}}.mesh"
  10.       port: "80"
  11.       parameters:
  12.         - name: service
  13.           tagKey: "kuma.io/service"
  14.         - name: version
  15.           tagKey: "kuma.io/version"

Custom tag to define the hostname and port

  1. apiVersion: kuma.io/v1alpha1
  2. kind: VirtualOutbound
  3. mesh: default
  4. metadata:
  5.   name: host-port
  6. spec:
  7.     selectors:
  8.       - match:
  9.           kuma.io/service: "*"
  10.     conf:
  11.       host: "{{.hostname}}"
  12.       port: "{{.port}}"
  13.       parameters:
  14.         - name: hostname
  15.           tagKey: "my.mesh/hostname"
  16.         - name: port
  17.           tagKey: "my.mesh/port"
  1. type: VirtualOutbound
  2. mesh: default
  3. name: host-port
  4. selectors:
  5.   - match:
  6.       kuma.io/service: "*"
  7. conf:
  8.   host: "{{.hostname}}"
  9.   port: "{{.port}}"
  10.   parameters:
  11.     - name: hostname
  12.       tagKey: "my.mesh/hostname"
  13.     - name: port
  14.       tagKey: "my.mesh/port"
  15.     - 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.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: VirtualOutbound
  3. mesh: default
  4. metadata:
  5.   name: instance
  6. spec:
  7.   selectors:
  8.     - match:
  9.         kuma.io/service: "*"
  10.         statefulset.kubernetes.io/pod-name: "*"
  11.   conf:
  12.     host: "{{.svc}}.{{.inst}}.mesh"
  13.     port: "8080"
  14.     parameters:
  15.       - name: "svc"
  16.         tagKey: "kuma.io/service"
  17.       - name: "inst"
  18.         tagKey: "statefulset.kubernetes.io/pod-name"
  1. type: VirtualOutbound
  2. mesh: default
  3. name: default
  4. selectors:
  5.   - match:
  6.       kuma.io/service: "*"
  7.       kuma.io/instance: "*"
  8. conf:
  9.   host: "inst-{{.instance}}.{{.service}}.mesh"
  10.   port: "8080"
  11.   parameters:
  12.     - name: service
  13.       tagKey: "kuma.io/service"
  14.     - name: instance
  15.       tagKey: "kuma.io/instance"