Thanks to visit codestin.com
Credit goes to github.com

Skip to content

plugin/nomad: Add a Nomad plugin #7467

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yongtang merged 1 commit into from
Sep 30, 2025
Merged

plugin/nomad: Add a Nomad plugin #7467

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions core/dnsserver/zdirectives.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,4 +64,5 @@ var Directives = []string{
"on",
"sign",
"view",
"nomad",
}
1 change: 1 addition & 0 deletions core/plugin/zplugin.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ import (
_ "github.com/coredns/coredns/plugin/metrics"
_ "github.com/coredns/coredns/plugin/minimal"
_ "github.com/coredns/coredns/plugin/multisocket"
_ "github.com/coredns/coredns/plugin/nomad"
_ "github.com/coredns/coredns/plugin/nsid"
_ "github.com/coredns/coredns/plugin/pprof"
_ "github.com/coredns/coredns/plugin/quic"
Expand Down
8 changes: 8 additions & 0 deletions go.mod
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ require (
github.com/farsightsec/golang-framestream v0.3.0
github.com/go-logr/logr v1.4.3
github.com/grpc-ecosystem/grpc-opentracing v0.0.0-20180507213350-8e809c8a8645
github.com/hashicorp/nomad/api v0.0.0-20250909143645-a3b86c697f38 // v1.10.5
github.com/infobloxopen/go-trees v0.0.0-20200715205103-96a057b8dfb9
github.com/matttproud/golang_protobuf_extensions v1.0.4
github.com/miekg/dns v1.1.68
Expand Down Expand Up @@ -115,14 +116,21 @@ require (
github.com/google/uuid v1.6.0 // indirect
github.com/googleapis/enterprise-certificate-proxy v0.3.6 // indirect
github.com/googleapis/gax-go/v2 v2.15.0 // indirect
github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 // indirect
github.com/grpc-ecosystem/grpc-gateway/v2 v2.26.3 // indirect
github.com/hashicorp/cronexpr v1.1.3 // indirect
github.com/hashicorp/errwrap v1.1.0 // indirect
github.com/hashicorp/go-cleanhttp v0.5.2 // indirect
github.com/hashicorp/go-multierror v1.1.1 // indirect
github.com/hashicorp/go-rootcerts v1.0.2 // indirect
github.com/hashicorp/go-version v1.7.0 // indirect
github.com/josharian/intern v1.0.0 // indirect
github.com/json-iterator/go v1.1.12 // indirect
github.com/kylelemons/godebug v1.1.0 // indirect
github.com/lufia/plan9stats v0.0.0-20250317134145-8bc96cf8fc35 // indirect
github.com/mailru/easyjson v0.7.7 // indirect
github.com/mitchellh/go-homedir v1.1.0 // indirect
github.com/mitchellh/mapstructure v1.5.1-0.20231216201459-8508981c8b6c // indirect
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee // indirect
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
Expand Down
21 changes: 21 additions & 0 deletions go.sum
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,8 @@ github.com/dimchansky/utfbom v1.1.1 h1:vV6w1AhK4VMnhBno/TPVCoK9U/LP0PkLCS9tbxHdi
github.com/dimchansky/utfbom v1.1.1/go.mod h1:SxdoEBH5qIqFocHMyGOXVAybYJdr71b1Q/j0mACtrfE=
github.com/dnstap/golang-dnstap v0.4.0 h1:KRHBoURygdGtBjDI2w4HifJfMAhhOqDuktAokaSa234=
github.com/dnstap/golang-dnstap v0.4.0/go.mod h1:FqsSdH58NAmkAvKcpyxht7i4FoBjKu8E4JUPt8ipSUs=
github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
github.com/dustin/go-humanize v1.0.0/go.mod h1:HtrtbFcZ19U5GC7JDqmcUSB87Iq5E25KnS6fMYU6eOk=
github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
Expand Down Expand Up @@ -207,12 +209,27 @@ github.com/googleapis/enterprise-certificate-proxy v0.3.6 h1:GW/XbdyBFQ8Qe+YAmFU
github.com/googleapis/enterprise-certificate-proxy v0.3.6/go.mod h1:MkHOF77EYAE7qfSuSS9PU6g4Nt4e11cnsDUowfwewLA=
github.com/googleapis/gax-go/v2 v2.15.0 h1:SyjDc1mGgZU5LncH8gimWo9lW1DtIfPibOG81vgd/bo=
github.com/googleapis/gax-go/v2 v2.15.0/go.mod h1:zVVkkxAQHa1RQpg9z2AUCMnKhi0Qld9rcmyfL1OZhoc=
github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 h1:JeSE6pjso5THxAzdVpqr6/geYxZytqFMBCOtn/ujyeo=
github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674/go.mod h1:r4w70xmWCQKmi1ONH4KIaBptdivuRPyosB9RmPlGEwA=
github.com/grpc-ecosystem/grpc-gateway/v2 v2.26.3 h1:5ZPtiqj0JL5oKWmcsq4VMaAW5ukBEgSGXEN89zeH1Jo=
github.com/grpc-ecosystem/grpc-gateway/v2 v2.26.3/go.mod h1:ndYquD05frm2vACXE1nsccT4oJzjhw2arTS2cpUD1PI=
github.com/grpc-ecosystem/grpc-opentracing v0.0.0-20180507213350-8e809c8a8645 h1:MJG/KsmcqMwFAkh8mTnAwhyKoB+sTAnY4CACC110tbU=
github.com/grpc-ecosystem/grpc-opentracing v0.0.0-20180507213350-8e809c8a8645/go.mod h1:6iZfnjpejD4L/4DwD7NryNaJyCQdzwWwH2MWhCA90Kw=
github.com/hashicorp/cronexpr v1.1.3 h1:rl5IkxXN2m681EfivTlccqIryzYJSXRGRNa0xeG7NA4=
github.com/hashicorp/cronexpr v1.1.3/go.mod h1:P4wA0KBl9C5q2hABiMO7cp6jcIg96CDh1Efb3g1PWA4=
github.com/hashicorp/errwrap v1.0.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
github.com/hashicorp/errwrap v1.1.0 h1:OxrOeh75EUXMY8TBjag2fzXGZ40LB6IKw45YeGUDY2I=
github.com/hashicorp/errwrap v1.1.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
github.com/hashicorp/go-cleanhttp v0.5.2 h1:035FKYIWjmULyFRBKPs8TBQoi0x6d9G4xc9neXJWAZQ=
github.com/hashicorp/go-cleanhttp v0.5.2/go.mod h1:kO/YDlP8L1346E6Sodw+PrpBSV4/SoxCXGY6BqNFT48=
github.com/hashicorp/go-multierror v1.1.1 h1:H5DkEtf6CXdFp0N0Em5UCwQpXMWke8IA0+lD48awMYo=
github.com/hashicorp/go-multierror v1.1.1/go.mod h1:iw975J/qwKPdAO1clOe2L8331t/9/fmwbPZ6JB6eMoM=
github.com/hashicorp/go-rootcerts v1.0.2 h1:jzhAVGtqPKbwpyCPELlgNWhE1znq+qwJtW5Oi2viEzc=
github.com/hashicorp/go-rootcerts v1.0.2/go.mod h1:pqUvnprVnM5bf7AOirdbb01K4ccR319Vf4pU3K5EGc8=
github.com/hashicorp/go-version v1.7.0 h1:5tqGy27NaOTB8yJKUZELlFAS/LTKJkrmONwQKeRZfjY=
github.com/hashicorp/go-version v1.7.0/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
github.com/hashicorp/nomad/api v0.0.0-20250909143645-a3b86c697f38 h1:1LTbcTpGdSdbj0ee7YZHNe4R2XqxfyWwIkSGWRhgkfM=
github.com/hashicorp/nomad/api v0.0.0-20250909143645-a3b86c697f38/go.mod h1:0Tdp+9HbvwrxprXv/LfYZ8P21bOl4oA8Afyet1kUvhI=
github.com/infobloxopen/go-trees v0.0.0-20200715205103-96a057b8dfb9 h1:w66aaP3c6SIQ0pi3QH1Tb4AMO3aWoEPxd1CNvLphbkA=
github.com/infobloxopen/go-trees v0.0.0-20200715205103-96a057b8dfb9/go.mod h1:BaIJzjD2ZnHmx2acPF6XfGLPzNCMiBbMRqJr+8/8uRI=
github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
Expand Down Expand Up @@ -243,6 +260,8 @@ github.com/miekg/dns v1.1.68 h1:jsSRkNozw7G/mnmXULynzMNIsgY2dHC8LO6U6Ij2JEA=
github.com/miekg/dns v1.1.68/go.mod h1:fujopn7TB3Pu3JM69XaawiU0wqjpL9/8xGop5UrTPps=
github.com/mitchellh/go-homedir v1.1.0 h1:lukF9ziXFxDFPkA1vsr5zpc1XuPDn/wFntq5mG+4E0Y=
github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
github.com/mitchellh/mapstructure v1.5.1-0.20231216201459-8508981c8b6c h1:cqn374mizHuIWj+OSJCajGr/phAmuMug9qIX3l9CflE=
github.com/mitchellh/mapstructure v1.5.1-0.20231216201459-8508981c8b6c/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
Expand Down Expand Up @@ -306,6 +325,8 @@ github.com/secure-systems-lab/go-securesystemslib v0.9.0 h1:rf1HIbL64nUpEIZnjLZ3
github.com/secure-systems-lab/go-securesystemslib v0.9.0/go.mod h1:DVHKMcZ+V4/woA/peqr+L0joiRXbPpQ042GgJckkFgw=
github.com/shirou/gopsutil/v4 v4.25.3 h1:SeA68lsu8gLggyMbmCn8cmp97V1TI9ld9sVzAUcKcKE=
github.com/shirou/gopsutil/v4 v4.25.3/go.mod h1:xbuxyoZj+UsgnZrENu3lQivsngRR5BdjbJwf2fv4szA=
github.com/shoenig/test v1.12.1 h1:mLHfnMv7gmhhP44WrvT+nKSxKkPDiNkIuHGdIGI9RLU=
github.com/shoenig/test v1.12.1/go.mod h1:UxJ6u/x2v/TNs/LoLxBNJRV9DiwBBKYxXSyczsBHFoI=
github.com/sirupsen/logrus v1.7.0/go.mod h1:yWOB1SBYBC5VeMP7gHvWumXLIWorT60ONWic61uBYv0=
github.com/spaolacci/murmur3 v1.1.0 h1:7c1g84S4BPRrfL5Xrdp6fOJ206sU9y293DDHaoy0bLI=
github.com/spaolacci/murmur3 v1.1.0/go.mod h1:JwIasOWyU6f++ZhiEuf87xNszmSA2myDM2Kzu9HwQUA=
Expand Down
292 changes: 292 additions & 0 deletions man/coredns-nomad.7
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,292 @@
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "COREDNS-NOMAD" 7 "September 2025" "CoreDNS" "CoreDNS Plugins"

.SH "NAME"
.PP
\fInomad\fP - enables reading zone data from a Nomad cluster.

.SH "DESCRIPTION"
.PP
This plugin serves DNS records for services registered with Nomad. Nomad 1.3+ comes with support for discovering services
\[la]https://www.hashicorp.com/en/blog/nomad-service-discovery\[ra] with an in-built service catalogue that is available via the HTTP API. This plugin extends the HTTP API and provides a DNS interface for querying the service catalogue.

.PP
The query can be looked up with the format \fB\fC[service].[namespace].service.nomad\fR. The plugin currently handles A, AAAA and SRV records. Refer to #Usage Example
\[la]#usage-example\[ra] for more details.

.SH "EXAMPLE JOB TEMPLATE"
.PP
.RS

.nf
job "dns" {
type = "service"

group "dns" {
network {
port "dns" {
static = 1053
}
}
task "dns" {
driver = "docker"

config {
image = "coredns/coredns:latest"
ports = ["dns"]
args = ["\-conf", "/secrets/coredns/Corefile", "\-dns.port", "1053"]
}

service {
name = "hostmaster"
provider = "nomad"
port = "dns"
address\_mode = "driver"
}

identity {
env = true
}

template {
data = <<EOF
\&. {
forward . 1.1.1.1
}

service.nomad. {
errors
debug
health
log
nomad service.nomad {
address unix:///secrets/api.sock
ttl 10
}
cache 30
}
EOF
destination = "secrets/coredns/Corefile"
change\_mode = "signal"
change\_signal = "SIGHUP"
}
}
}
}

.fi
.RE

.SH "SYNTAX"
.PP
.RS

.nf
nomad [ZONE] {

.fi
.RE

.PP
With only the plugin specified, the \fInomad\fP plugin will default to \fB\fCservice.nomad\fR zone.

.PP
.RS

.nf
nomad [ZONE] {
address URL
token TOKEN
ttl DURATION
}

.fi
.RE

.IP \(bu 4
\fB\fCaddress\fR The address where a Nomad agent (server) is available. \fBURL\fP defaults to \fB\fChttp://127.0.0.1:4646\fR.
.IP \(bu 4
\fB\fCtoken\fR The SecretID of an ACL token to use to authenticate API requests with if the Nomad cluster has ACL enabled. \fBTOKEN\fP defaults to \fB\fC""\fR.
.IP \(bu 4
\fB\fCttl\fR allows you to set a custom TTL for responses. \fBDURATION\fP defaults to \fB\fC30 seconds\fR. The minimum TTL allowed is \fB\fC0\fR seconds, and the maximum is capped at \fB\fC3600\fR seconds. Setting TTL to 0 will prevent records from being cached. The unit for the value is seconds.


.SH "METRICS"
.PP
If monitoring is enabled (via the \fIprometheus\fP directive) the following metric is exported:

.IP \(bu 4
\fB\fCcoredns_nomad_success_requests_total{namespace,server}\fR - Counter of DNS requests handled successfully.
.IP \(bu 4
\fB\fCcoredns_nomad_failed_requests_total{namespace,server}\fR - Counter of DNS requests failed.


.PP
The \fB\fCserver\fR label indicated which server handled the request. \fB\fCnamespace\fR indicates the namespace of the service in the query.

.SH "READY"
.PP
This plugin reports readiness to the ready plugin. It will be ready only when it has successfully connected to the Nomad server. It queries the \fB\fC/v1/agent/self\fR
\[la]https://developer.hashicorp.com/nomad/api-docs/agent#query-self\[ra] endpoint to check if it is ready.

.SH "EXAMPLES"
.PP
Enable nomad with and resolve all services with \fB\fC.nomad\fR as the suffix. \fB\fCcache\fR plugin is used to cache the responses for 30 seconds. This avoids a lookup to the Nomad server for every request.

.PP
.RS

.nf
service.nomad.:1053 {
log
cache
errors
nomad service.nomad {
address http://127.0.0.1:4646 http://127.0.0.2:4646 http://127.0.0.3:4646
ttl 10
}
cache 30
}

.fi
.RE

.SH "AUTHENTICATION"
.PP
\fB\fCnomad\fR plugin uses a default Nomad configuration to create an API client. Options like the HTTP address and the token can be specified in Corefile. However, Nomad Go SDK can also additionally read these environment variables.

.IP \(bu 4
\fB\fCNOMAD_TOKEN\fR
.IP \(bu 4
\fB\fCNOMAD_ADDR\fR
.IP \(bu 4
\fB\fCNOMAD_REGION\fR
.IP \(bu 4
\fB\fCNOMAD_NAMESPACE\fR
.IP \(bu 4
\fB\fCNOMAD_HTTP_AUTH\fR
.IP \(bu 4
\fB\fCNOMAD_CACERT\fR
.IP \(bu 4
\fB\fCNOMAD_CAPATH\fR
.IP \(bu 4
\fB\fCNOMAD_CLIENT_CERT\fR
.IP \(bu 4
\fB\fCNOMAD_CLIENT_KEY\fR
.IP \(bu 4
\fB\fCNOMAD_TLS_SERVER_NAME\fR
.IP \(bu 4
\fB\fCNOMAD_SKIP_VERIFY\fR


.PP
You can read about them in detail here
\[la]https://developer.hashicorp.com/nomad/docs/reference/runtime-environment-settings\[ra].

.SH "USAGE EXAMPLE"
.SS "A RECORD"
.PP
.RS

.nf
dig redis.default.service.nomad @127.0.0.1 \-p 1053

; <<>> DiG 9.18.1\-1ubuntu1.2\-Ubuntu <<>> redis.default.service.nomad @127.0.0.1 \-p 1053
;; global options: +cmd
;; Got answer:
;; \->>HEADER<<\- opcode: QUERY, status: NOERROR, id: 54986
;; flags: qr aa rd; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 1
;; WARNING: recursion requested but not available

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 1232
; COOKIE: bdc9237f49a1f744 (echoed)
;; QUESTION SECTION:
;redis.default.service.nomad. IN A

;; ANSWER SECTION:
redis.default.service.nomad. 10 IN A 192.168.29.76
redis.default.service.nomad. 10 IN A 192.168.29.76
redis.default.service.nomad. 10 IN A 192.168.29.76

;; Query time: 4 msec
;; SERVER: 127.0.0.1#1053(127.0.0.1) (UDP)
;; WHEN: Thu Jan 05 12:12:25 IST 2023
;; MSG SIZE rcvd: 165

.fi
.RE

.SS "SRV RECORD"
.PP
Since an A record doesn't contain the port number, SRV record can be used to query the port number of a service.

.PP
.RS

.nf
dig redis.default.service.nomad @127.0.0.1 \-p 1053 SRV

; <<>> DiG 9.18.1\-1ubuntu1.2\-Ubuntu <<>> redis.default.service.nomad @127.0.0.1 \-p 1053 SRV
;; global options: +cmd
;; Got answer:
;; \->>HEADER<<\- opcode: QUERY, status: NOERROR, id: 49945
;; flags: qr aa rd; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 4
;; WARNING: recursion requested but not available

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 1232
; COOKIE: 14572535f3ba6648 (echoed)
;; QUESTION SECTION:
;redis.default.service.nomad. IN SRV

;; ANSWER SECTION:
redis.default.service.nomad. 8 IN SRV 10 10 25395 redis.default.service.nomad.
redis.default.service.nomad. 8 IN SRV 10 10 20888 redis.default.service.nomad.
redis.default.service.nomad. 8 IN SRV 10 10 26292 redis.default.service.nomad.

;; ADDITIONAL SECTION:
redis.default.service.nomad. 8 IN A 192.168.29.76
redis.default.service.nomad. 8 IN A 192.168.29.76
redis.default.service.nomad. 8 IN A 192.168.29.76

;; Query time: 0 msec
;; SERVER: 127.0.0.1#1053(127.0.0.1) (UDP)
;; WHEN: Thu Jan 05 12:12:20 IST 2023
;; MSG SIZE rcvd: 339

.fi
.RE

.SS "SOA RECORD"
.PP
.RS

.nf
$ dig @localhost \-p 1053 1dns.default.service.nomad.

; <<>> DiG 9.18.12\-0ubuntu0.22.04.2\-Ubuntu <<>> @localhost \-p 1053 1dns.default.service.nomad.
; (1 server found)
;; global options: +cmd
;; Got answer:
;; \->>HEADER<<\- opcode: QUERY, status: NXDOMAIN, id: 21012
;; flags: qr aa rd; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
;; WARNING: recursion requested but not available

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 1232
; COOKIE: 6d146bb140b4d8ca (echoed)
;; QUESTION SECTION:
;1dns.default.service.nomad. IN A

;; ANSWER SECTION:
1dns.default.service.nomad. 5 IN SOA ns1.1dns.default.service.nomad. ns1.1dns.default.service.nomad. 1 3600 600 604800 3600

;; Query time: 0 msec
;; SERVER: 127.0.0.1#1053(localhost) (UDP)
;; WHEN: Wed Aug 23 21:14:41 EEST 2023
;; MSG SIZE rcvd: 189

.fi
.RE

1 change: 1 addition & 0 deletions plugin.cfg
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,3 +73,4 @@ whoami:whoami
on:github.com/coredns/caddy/onevent
sign:sign
view:view
nomad:nomad
Loading
Loading