Kuma Star

Careful!

You are browsing documentation for a version of Kuma that is not the latest release.

Looking for even older versions? Learn more.

HostnameGenerator

This resource is experimental!

A HostnameGenerator provides

  • a template to generate hostnames from properties of MeshServices, MeshMultiZoneService, and MeshExternalServices
  • a selector that defines for which MeshServices, MeshMultiZoneService, and MeshExternalServices this generator runs

Defaults

Kuma ships with default HostnameGenerators depending on the control plane mode and storage type.

Local MeshService in Universal zone

The following policy is automatically created on a zone control plane running in the Universal mode. It creates a hostname for each MeshService created in a zone. For example, MeshService of name redis would obtain redis.svc.mesh.local hostname.

type: HostnameGenerator
name: local-universal-mesh-service
spec:
  selector:
    meshService:
      matchLabels:
        kuma.io/origin: zone
  template: "{{ .DisplayName }}.svc.mesh.local"

Local MeshExternalService

The following policy is automatically created on a zone control plane. It creates a hostname for each MeshExternalService created in a zone. For example, MeshExternalService of name aurora would obtain aurora.extsvc.mesh.local hostname.

apiVersion: kuma.io/v1alpha1
kind: HostnameGenerator
metadata:
  name: local-mesh-external-service
  namespace: kuma-system
  labels:
    kuma.io/mesh: 
spec:
  selector:
    meshExternalService:
      matchLabels:
        kuma.io/origin: zone
  template: "{{ .DisplayName }}.extsvc.mesh.local"

Synced MeshService from Kubernetes zone

The following policies are automatically created on a global control plane and synced to all zones.

The first creates a hostname for each MeshService synced from another Kubernetes zone. For example, MeshService of name redis and namespace redis-system from zone east would obtain redis.redis-system.svc.east.mesh.local

apiVersion: kuma.io/v1alpha1
kind: HostnameGenerator
metadata:
  name: synced-kube-mesh-service
  namespace: kuma-system
  labels:
    kuma.io/mesh: 
spec:
  selector:
    meshService:
      matchLabels:
        kuma.io/origin: global
        k8s.kuma.io/is-headless-service: false
        kuma.io/env: kubernetes
  template: "{{ .DisplayName }}.{{ .Namespace }}.svc.{{ .Zone }}.mesh.local"

The second creates a hostname for each MeshService synced from another Kubernetes zone that were created from a headless Service. For example, instance redis-0 of MeshService of name redis and namespace redis-system from zone east would obtain redis-0.redis.redis-system.svc.east.mesh.local

apiVersion: kuma.io/v1alpha1
kind: HostnameGenerator
metadata:
  name: synced-headless-kube-mesh-service
  namespace: kuma-system
  labels:
    kuma.io/mesh: 
spec:
  selector:
    meshService:
      matchLabels:
        kuma.io/origin: global
        k8s.kuma.io/is-headless-service: true
        kuma.io/env: kubernetes
  template: "{{ label 'statefulset.kubernetes.io/pod-name' }}.{{ label 'k8s.kuma.io/service-name'
    }}.{{ .Namespace }}.svc.{{ .Zone }}.mesh.local"

Synced MeshService from Universal zone

The following policy is automatically created on a global control plane and synced to all zones. It creates a hostname for each MeshService synced from another Universal zone. For example, MeshService of name redis from zone west would obtain redis.svc.west.mesh.local

apiVersion: kuma.io/v1alpha1
kind: HostnameGenerator
metadata:
  name: synced-universal-mesh-service
  namespace: kuma-system
  labels:
    kuma.io/mesh: 
spec:
  selector:
    meshService:
      matchLabels:
        kuma.io/origin: global
        kuma.io/env: universal
  template: "{{ .DisplayName }}.svc.{{ .Zone }}.mesh.local"

Synced MeshMultiZoneService from a global control plane

The following policy is automatically created on a global control plane and synced to all zones. It creates a hostname for each MeshMultiZoneService synced from a global control plane. For example, MeshMultiZoneService of name redis would obtain redis.mzsvc.mesh.local

apiVersion: kuma.io/v1alpha1
kind: HostnameGenerator
metadata:
  name: synced-mesh-multi-zone-service
  namespace: kuma-system
  labels:
    kuma.io/mesh: 
spec:
  selector:
    meshMultiZoneService:
      matchLabels:
        kuma.io/origin: global
  template: "{{ .DisplayName }}.mzsvc.mesh.local"

Synced MeshExternalService from a global control plane

The following policy is automatically created on a global control plane and synced to all zones. It creates a hostname for each MeshExternalService synced from a global control plane. For example, MeshExternalService of name aurora would obtain aurora.extsvc.mesh.local

apiVersion: kuma.io/v1alpha1
kind: HostnameGenerator
metadata:
  name: synced-mesh-external-service
  namespace: kuma-system
  labels:
    kuma.io/mesh: 
spec:
  selector:
    meshExternalService:
      matchLabels:
        kuma.io/origin: global
  template: "{{ .DisplayName }}.extsvc.mesh.local"

Template

A template is a golang text template. It is run with the function label to retrieve labels of the MeshService, MeshMultiZoneService or MeshExternalService as well as the following attributes:

  • .DisplayName: the name of the resource in its original zone
  • .Namespace: the namespace of the resource in its original zone, if kubernetes
  • .Zone: the zone of the resource
  • .Mesh: the mesh of the resource

For example, given:

kind: MeshService
metadata:
  name: redis
  namespace: kuma-demo
  labels:
    kuma.io/mesh: products
    team: backend
    k8s.kuma.io/service-name: redis
    k8s.kuma.io/namespace: kuma-demo

and

template: "{{ .DisplayName }}.{{ .Namespace }}.{{ .Mesh }}.{{ label "team" }}.mesh.local"

the generated hostname would be:

redis.kuma-demo.products.backend.mesh.local

The generated hostname points to the first VIP known for the MeshService.

Status

Every generated hostname is recorded on the MeshService status in addresses:

status:
  addresses:
    - hostname: redis.kuma-demo.svc.east.mesh.local
      origin: HostnameGenerator
      hostnameGeneratorRef:
        coreName: synced-kube-mesh-service