Careful!

You are browsing documentation for the next version of Kuma. Use this version at your own risk.

HostnameGenerator

HostnameGenerator generates DNS hostnames for service resources using customizable templates. It allows you to define consistent naming patterns for MeshService, MeshMultiZoneService, and MeshExternalService resources based on their properties and labels.

Kuma automatically creates default HostnameGenerator resources based on control plane mode and environment to provide familiar DNS patterns. You can create custom generators for specific naming requirements.

For concepts, default configurations, and usage patterns, see the HostnameGenerator guide.

Spec fields

Field	Description
`selector`	Defines which service resources this generator applies to. Use one of `meshService`, `meshExternalService`, or `meshMultiZoneService`.
`selector.meshService.matchLabels`	Match `MeshService` resources by labels. All specified labels must match.
`selector.meshExternalService.matchLabels`	Match `MeshExternalService` resources by labels. All specified labels must match.
`selector.meshMultiZoneService.matchLabels`	Match `MeshMultiZoneService` resources by labels. All specified labels must match.
`template`	Go text template for generating hostnames. Required field.
`extension`	Plugin configuration for custom hostname generation logic. Optional.
`extension.type`	Type identifier for the extension plugin.
`extension.config`	Freeform configuration passed to the extension.

Template variables

The template has access to:

.DisplayName - Resource name in original zone
.Namespace - Resource namespace (Kubernetes only)
.Zone - Zone where resource originated
.Mesh - Mesh name
label "key" - Function to retrieve resource labels

Status fields

Status is managed by Kuma on service resources that have generated hostnames:

Field	Description
`addresses[].hostname`	Generated hostname.
`addresses[].origin`	Set to `HostnameGenerator`.
`addresses[].hostnameGeneratorRef.coreName`	Name of the `HostnameGenerator` that created this hostname.

Examples

Basic HostnameGenerator for MeshService

Kubernetes
Universal

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

HostnameGenerator with namespace and zone

Kubernetes
Universal

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

type: HostnameGenerator
name: synced-kube-mesh-service
spec:
  selector:
    meshService:
      matchLabels:
        kuma.io/origin: global
        kuma.io/env: kubernetes
  template: "{{ .DisplayName }}.{{ .Namespace }}.svc.{{ .Zone }}.mesh.local"

This generates hostnames like redis.kuma-demo.svc.east.mesh.local for a MeshService named redis in namespace kuma-demo from zone east.

HostnameGenerator with label function

Kubernetes
Universal

apiVersion: kuma.io/v1alpha1
kind: HostnameGenerator
metadata:
  name: custom-headless
  namespace: kuma-system
spec:
  selector:
    meshService:
      matchLabels:
        k8s.kuma.io/is-headless-service: "true"
  template: "{{ label \"statefulset.kubernetes.io/pod-name\" }}.{{ label \"k8s.kuma.io/service-name\" }}.{{ .Namespace }}.svc.mesh.local"

type: HostnameGenerator
name: custom-with-labels
spec:
  selector:
    meshService:
      matchLabels:
        team: backend
  template: "{{ .DisplayName }}.{{ label \"environment\" }}.mesh.local"

HostnameGenerator for MeshExternalService

Kubernetes
Universal

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

type: HostnameGenerator
name: mesh-external-service
spec:
  selector:
    meshExternalService:
      matchLabels:
        kuma.io/origin: zone
  template: "{{ .DisplayName }}.extsvc.mesh.local"

HostnameGenerator for MeshMultiZoneService

Kubernetes
Universal

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

type: HostnameGenerator
name: mesh-multi-zone-service
spec:
  selector:
    meshMultiZoneService:
      matchLabels:
        kuma.io/origin: global
  template: "{{ .DisplayName }}.mzsvc.mesh.local"

See also

All options

Kind is a string value representing the REST resource this object represents. Servers may infer this...

Spec is the specification of the Kuma HostnameGenerator resource.

Extension struct for a plugin configuration

Type of the extension.

Config freeform configuration for the extension.

APIVersion defines the versioned schema of this representation of an object. Servers should convert ...