HostnameGenerator

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.

  1. type: HostnameGenerator
  2. name: local-universal-mesh-service
  3. spec:
  4.   selector:
  5.     meshService:
  6.       matchLabels:
  7.         kuma.io/origin: zone
  8.   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.

  1. apiVersion: kuma.io/v1alpha1
  2. kind: HostnameGenerator
  3. metadata:
  4.   name: local-mesh-external-service
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: 
  8. spec:
  9.   selector:
  10.     meshExternalService:
  11.       matchLabels:
  12.         kuma.io/origin: zone
  13.   template: "{{ .DisplayName }}.extsvc.mesh.local"
  1. type: HostnameGenerator
  2. name: local-mesh-external-service
  3. spec:
  4.   selector:
  5.     meshExternalService:
  6.       matchLabels:
  7.         kuma.io/origin: zone
  8.   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

  1. apiVersion: kuma.io/v1alpha1
  2. kind: HostnameGenerator
  3. metadata:
  4.   name: synced-kube-mesh-service
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: 
  8. spec:
  9.   selector:
  10.     meshService:
  11.       matchLabels:
  12.         kuma.io/origin: global
  13.         k8s.kuma.io/is-headless-service: false
  14.         kuma.io/env: kubernetes
  15.   template: "{{ .DisplayName }}.{{ .Namespace }}.svc.{{ .Zone }}.mesh.local"
  1. type: HostnameGenerator
  2. name: synced-kube-mesh-service
  3. spec:
  4.   selector:
  5.     meshService:
  6.       matchLabels:
  7.         kuma.io/origin: global
  8.         k8s.kuma.io/is-headless-service: false
  9.         kuma.io/env: kubernetes
  10.   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

  1. apiVersion: kuma.io/v1alpha1
  2. kind: HostnameGenerator
  3. metadata:
  4.   name: synced-headless-kube-mesh-service
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: 
  8. spec:
  9.   selector:
  10.     meshService:
  11.       matchLabels:
  12.         kuma.io/origin: global
  13.         k8s.kuma.io/is-headless-service: true
  14.         kuma.io/env: kubernetes
  15.   template: "{{ label 'statefulset.kubernetes.io/pod-name' }}.{{ label 'k8s.kuma.io/service-name'
  16.     }}.{{ .Namespace }}.svc.{{ .Zone }}.mesh.local"
  1. type: HostnameGenerator
  2. name: synced-headless-kube-mesh-service
  3. spec:
  4.   selector:
  5.     meshService:
  6.       matchLabels:
  7.         kuma.io/origin: global
  8.         k8s.kuma.io/is-headless-service: true
  9.         kuma.io/env: kubernetes
  10.   template: "{{ label 'statefulset.kubernetes.io/pod-name' }}.{{ label 'k8s.kuma.io/service-name'
  11.     }}.{{ .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

  1. apiVersion: kuma.io/v1alpha1
  2. kind: HostnameGenerator
  3. metadata:
  4.   name: synced-universal-mesh-service
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: 
  8. spec:
  9.   selector:
  10.     meshService:
  11.       matchLabels:
  12.         kuma.io/origin: global
  13.         kuma.io/env: universal
  14.   template: "{{ .DisplayName }}.svc.{{ .Zone }}.mesh.local"
  1. type: HostnameGenerator
  2. name: synced-universal-mesh-service
  3. spec:
  4.   selector:
  5.     meshService:
  6.       matchLabels:
  7.         kuma.io/origin: global
  8.         kuma.io/env: universal
  9.   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

  1. apiVersion: kuma.io/v1alpha1
  2. kind: HostnameGenerator
  3. metadata:
  4.   name: synced-mesh-multi-zone-service
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: 
  8. spec:
  9.   selector:
  10.     meshMultiZoneService:
  11.       matchLabels:
  12.         kuma.io/origin: global
  13.   template: "{{ .DisplayName }}.mzsvc.mesh.local"
  1. type: HostnameGenerator
  2. name: synced-mesh-multi-zone-service
  3. spec:
  4.   selector:
  5.     meshMultiZoneService:
  6.       matchLabels:
  7.         kuma.io/origin: global
  8.   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

  1. apiVersion: kuma.io/v1alpha1
  2. kind: HostnameGenerator
  3. metadata:
  4.   name: synced-mesh-external-service
  5.   namespace: kuma-system
  6.   labels:
  7.     kuma.io/mesh: 
  8. spec:
  9.   selector:
  10.     meshExternalService:
  11.       matchLabels:
  12.         kuma.io/origin: global
  13.   template: "{{ .DisplayName }}.extsvc.mesh.local"
  1. type: HostnameGenerator
  2. name: synced-mesh-external-service
  3. spec:
  4.   selector:
  5.     meshExternalService:
  6.       matchLabels:
  7.         kuma.io/origin: global
  8.   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:

  1. kind: MeshService
  2. metadata:
  3.   name: redis
  4.   namespace: kuma-demo
  5.   labels:
  6.     kuma.io/mesh: products
  7.     team: backend
  8.     k8s.kuma.io/service-name: redis
  9.     k8s.kuma.io/namespace: kuma-demo

and

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

the generated hostname would be:

  1. 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:

  1. status:
  2.   addresses:
  3.     - hostname: redis.kuma-demo.svc.east.mesh.local
  4.       origin: HostnameGenerator
  5.       hostnameGeneratorRef:
  6.         coreName: synced-kube-mesh-service