This repo has been officially deprecated in favor of the https://github.com/kubernetes-incubator/external-dns addon. That addon offers a lot more features, better performance, and a compatibility mode for current users of Mate
. See compatibility mode docs here.
Mate synchronizes AWS Route53 or Google CloudDNS records with exposed Kubernetes services and ingresses.
When creating ingress objects or services with Type=LoadBalancer
Kubernetes provisions an external load balancer to forward traffic to its cluster IP. Depending on the cloud provider this load balancer will get a random public IP or DNS name but no defined DNS record to point to it.
Mate bridges this gap and synchronizes DNS records based on the service's or ingress' name and/or namespace. This allows exposed services to be seamlessly discovered even if the load balancer address changes or isn't known beforehand. Additionally, Mate can create DNS entries for each of your Type=NodePort
services pointing to all nodes in your cluster.
go get github.com/zalando-incubator/mate
or
docker run registry.opensource.zalan.do/teapot/mate:v0.6.2 --help
- Supports both Google and Amazon Cloud Providers
- Complete and safe management of DNS records for both services and ingress resources. Only records created by Mate will be updated and deleted.
- Immediate updates via Kubernetes event listener and periodic resync of all endpoints to match the Kubernetes state.
- Allows to specify record DNS via Service Annotations, Ingress Rules or passed in go-template
- Pluggable consumers and producers (see below)
- Supports multiple hosted zones in AWS Route53
Depending on the cloud provider the invocation differs slightly. For more detailed step-by-step guide see examples.
$ mate \
--producer=kubernetes \
--kubernetes-format="{{.Namespace}}-{{.Name}}.example.com" \
--consumer=aws \
--aws-record-group-id=foo
For each exposed service Mate will create two records in Route53:
-
A record - An Alias to the ELB with the name inferred from
kubernetes-format
orzalando.org/dnsname
annotation. When using ingress DNS records based on the hostnames in your rules will be created. -
TXT record - A TXT record that will have the same name as an A record and a special identifier with an embedded
aws-record-group-id
value. This helps to identify which records are created via Mate and makes it safe not to overwrite manually created records.
$ mate \
--producer=kubernetes \
--kubernetes-format="{{.Namespace}}-{{.Name}}.example.com" \
--consumer=google \
--google-project=bar \
--google-zone=example-com \
--google-record-group-id=foo
Analogous to the AWS case with the difference that it doesn't use the AWS specific Alias functionality but plain A records.
Mate needs permission to modify DNS records in your chosen cloud provider. On GCP this maps to using service accounts and scopes, on AWS to IAM roles and policies. For detailed instructions see the examples.
Mate will listen for events from the API Server and create corresponding
records for newly created services. Further synchronization (create, update and
removal) will occur every minute. There's an initial syncronization when Mate
boots up so it's safe to reboot the process at any point in time. If you only
like to do the synchronization you can use the sync-only
flag.
By default Mate uses the in cluster environment to configure the connection to
the API server. When running outside a cluster it is possible to configure the
API server url using the flag kubernetes-server
. For instance you can run
Mate locally with the server URL set to http://127.0.0.1:8001
and use
kubectl proxy
to forward requests to a cluster.
In Zalando we use our in-house built ingress controller on AWS - kube-ingress-aws-controller which makes the whole setup super simple and it is production tested. Please refer to the ingress section for usage manual.
Mate supports swapping out Endpoint producers (e.g. a service list from Kubernetes) and endpoint consumers (e.g. making API calls to Google to create DNS records) and both sides are pluggable. There currently exist two producer and three consumer implementations.
Kubernetes
: watches kubernetes services and ingresses with exactly one external IP or DNS nameFake
: generates random endpoints simulating a very busy cluster
Google
: listens for endpoints and creates Google CloudDNS entries accordinglyAWS
: listens for endpoints and creates AWS Route53 DNS entriesStdout
: listens for endpoints and prints them to Stdout
You can choose any combination. Kubernetes
+ Stdout
is useful for testing your service watching functionality, whereas Fake
+ Google
is useful for testing that you create the correct records in GCP.
- Although the modular design allows to specify it, you currently cannot create DNS records on Google CloudDNS for a cluster running on AWS because AWS ELBs will send ELB endpoints in the form of DNS names whereas the Google consumer expects them to be IPs and vice versa.
- Creating DNS entries for NodePort services doesn't currently work in combination with the AWS consumer.
By default mate
will process all Services and Ingresses in all namespaces. This can lead to conflicts with other controllers such as kops' dns-controller or wearemolecule's route53-kubernetes. In order to avoid conflicts with other implementations or for when you want opt-in behaviour you can start mate
with the --kubernetes-filter
flag passing it an annotation selector to filter Services and Ingresses for. For example,
$ ./mate \
--producer kubernetes \
--kubernetes-filter external-dns.alpha.kubernetes.io/controller=mate \
[...]
will only consider Services and Ingresses annotated with external-dns.alpha.kubernetes.io/controller=mate
.
The MIT License (MIT)
Copyright (c) 2016 Zalando SE
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.