Careful!
You are browsing documentation for the next version of Kuma. Use this version at your own risk.
HostnameGenerator
A HostnameGenerator
provides
- a template to generate hostnames from properties of
MeshServices
,MeshMultiZoneService
, andMeshExternalServices
- a selector that defines for which
MeshServices
,MeshMultiZoneService
, andMeshExternalServices
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: {}
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: {}
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: {}
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: {}
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: {}
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: {}
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