feat(source): add Nomad service

[kiurchv]

Description

This PR introduces a new source for ExternalDNS: nomad-service.

The purpose of this source is to allow ExternalDNS to discover DNS endpoints from services registered in HashiCorp Nomad, a flexible workload orchestrator. This enables ExternalDNS users to manage DNS records for workloads orchestrated by Nomad using the same toolset they already use for Kubernetes and other platforms.

Nomad provides native service discovery and a metadata-rich API. This source leverages the service metadata—specifically, service tags—to configure DNS endpoints.

Example

Here's an example of a Nomad job that registers a service with DNS configuration:

job "whoami" {
  group "demo" {
    network {
      mode = "host"

      port "http" {
        static = 80
      }
    }

    service {
      name = "whoami-demo"
      port = "http"
      provider = "nomad"
      tags = [
        "external-dns.hostname=whoami.example.org.",
      ]
    }

    task "server" {
      driver = "docker"

      config {
        image = "traefik/whoami"
        ports = ["http"]
      }

      env {
        WHOAMI_PORT_NUMBER = "${NOMAD_PORT_http}"
      }
    }
  }
}

This job will result in ExternalDNS creating a DNS record for whoami.example.org. pointing to the service's IP address.

CLI Flags

The following optional command-line flags were introduced to configure the Nomad client used by the source:

--nomad-address=""             Nomad endpoint address. If empty, defaults to $NOMAD_ADDR or http://127.0.0.1:4646
--nomad-region=""              Nomad region to use. If not provided, the default agent region is used
--nomad-token=NOMAD-TOKEN      Nomad per-request ACL token
--nomad-wait-time=0s           WaitTime limits how long a Watch will block. If not provided, the agent default values will be used

Example Usage

To run ExternalDNS with the nomad-service source and an in-memory provider:

external-dns \
  --source=nomad-service \
  --provider=inmemory \
  --nomad-address=http://127.0.0.1:4646

Note on Nomad Tags vs Kubernetes Annotations

Nomad does not have annotations like Kubernetes, so ExternalDNS-specific configuration is done through service tags.

Unlike Kubernetes annotations, which are a key-value map, Nomad tags are represented as a flat array of strings. To work around this difference, the implementation expects tags to follow a key=value format under the external-dns. prefix.

For example:

tags = [
  "external-dns.hostname=example.nomad.internal.",
  "external-dns.ttl=300",
  "external-dns.controller=dns-controller",
  "external-dns.set-identifier=my-id"
]

Most of ExternalDNS annotations are supported via tags (e.g., hostname, TTL, target, etc.), provider-specific configuration is also supported.

---

This integration:

• Provides a consistent developer experience across platforms like Kubernetes and Nomad
• Enables automated DNS record management for Nomad-deployed services
• Uses the pluggable ExternalDNS architecture to extend support to non-Kubernetes orchestrators

Checklist

• Unit tests updated
• End user documentation updated

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: kiurchv / name: Myroslav Kiurchev (0959ee2, f997a1c, 9e5b7eb, 2c13ebe)

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign raffo for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[k8s-ci-robot]

Welcome @kiurchv!

It looks like this is your first PR to kubernetes-sigs/external-dns 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/external-dns has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[k8s-ci-robot]

Hi @kiurchv. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[ivankatliarchuk]

Nomad is not a kubernetes source, it's completely different orchestrator/scheduler. Could you explain a little bit more how the integration suppose to work? And what is wrong with native Nomad + Consul DNS handling that is the reccomeded way of doing things on that platform?

[kiurchv]

@ivankatliarchuk Like a Kubernetes Nomad have similar services concept and similar to Kubernetes services each Nomad service points to a workload instance IP address. And since ExternalDNS architecture allows to implement any Source to be independent of Kubernetes cluster presence and run controller application in any orchestrator/scheduler setup I don't see any issues with running ExternalDNS inside Nomad cluster. There are already present CloudFoundry source which is using only CloudFoundry API and not depends on Kubernetes.

Historically Nomad has an integration with Consul service discovery (which allows to achieve service address resolution via DNS similar to Kubernetes internal DNS naming). Also, since version 1.3 Nomad has native service discovery mechanism, which enables service discovery via Nomad API (but not via DNS). Neither of these service discovery mechanisms address the problem which solves ExternalDNS.

There are similar solutions present such as nomad-external-dns and D53 but they are pretty limited in terms of feature set and provider support.

So my proposal to add a new source implementation to ExternalDNS seems like a shortest and unobtrusive way to bring such functionality to Nomad

[ivankatliarchuk]

My concern isn't with Nomad itself, but whether it effectively serves our project's target audience. I have no opinion, opeartional support could be tricky as we are mainly kubernetes experts, but could be an interesting experiment.

@mloiseleur @Raffo @szuecs wdyt?

[mloiseleur]

@ivankatliarchuk Why not ? It's interesting to have alternatives.

@kiurchv First, thanks for this proposal.

Is this possible to strictly align current k8s annotations with nomad service tags ?

[kiurchv]

@mloiseleur Thanks for your attention.

Sure this is possible. Actually the current implementation with shortened annotation names was inspired by similar Traefik's Nomad service discovery integration: https://doc.traefik.io/traefik/routing/providers/nomad

So if we're using Traefik as load balancer in Nomad cluster such service configuration could look like this (example from the real Nomad job):

service {
  name = "whoami"
  port = "http"
  provider = "nomad"
  tags = [
    "external-dns.hostname=whoami.internal",
    "external-dns.target=${attr.unique.network.ip-address}",
    "traefik.enable=true",
    "traefik.http.routers.http.rule=Host(`whoami.internal`)",
  ]
}

[ivankatliarchuk]

/ok-to-test

[ivankatliarchuk]

/label tide/merge-method-squash

[mloiseleur]

Actually the current implementation with shortened annotation names was inspired by similar Traefik's Nomad service discovery integration

Thanks, it's more clear. Maybe we will do the same for k8s annotations one day :).

[mloiseleur]

Wdyt of put this into a func ? And use it in the if L144 ?

[kiurchv]

Good point! Actually this code was shamelessly copied from existing ServiceSource implementation, so I guess it will be better to move this whole sorting thing into own func too

[mloiseleur]

Does that mean that it will work only for creation ? That delete / update / add of a nomad service won't be taken into account ?

[kiurchv]

Any service changes will be taken into account since Endpoints method should return all actual endpoints from all present services and reconciling of next endpoints state etc happens outside of the Source scope.

Speaking of AddEventHandler method — it is used only when --events CLI flag is enabled and allows to subscribe to source changes and update endpoints accordingly in addition to default polling-based approach.
Actually Nomad itself provides such API which allows to subscribe to service changes and I'm planning to implement this method too

[mloiseleur]

This PR LGTM.

@kiurchv Do you think you can rebase this PR ?
We need one or two review and we should be good to go.

If this cannot make it for the release, I'm thinking about adding a line about this PR in order to find some interested nomad users to come and review this PR.

/retitle feat(source): add Nomad service

[kiurchv]

@mloiseleur Done. Also, I've moved duplicated ServiceSource code into own function

[ivankatliarchuk]

Probably worth rewrite to a method comment

[ivankatliarchuk]

Probably worth to create NomadConfig?

[ivankatliarchuk]

We may need some examples for FQDN template, as not sure at the moment how it should work. Docs here http://github.com/kubernetes-sigs/external-dns/blob/master/docs/advanced/fqdn-templating.md. This could be added as follow up

[ivankatliarchuk]

Is nomad require no authentication? Any RBAC required to list services in namespace or in all namespaces?

[ivankatliarchuk]

is this required? If not let's remove commented code

[ivankatliarchuk]

receiver names are different, sc, ns etc

[ivankatliarchuk]

Suggested change

	func (ns *nomadServiceSource) Endpoints(ctx context.Context) ([]*endpoint.Endpoint, error) {
	func (ns *nomadServiceSource) Endpoints(_ context.Context) ([]*endpoint.Endpoint, error) {

context not in use at the moment

[ivankatliarchuk]

Suggested change

	endpoints := []*endpoint.Endpoint{}
	var endpoints []*endpoint.Endpoint

emtpy slice declaration uses a literal. let's replace with nill slice declaration, we are going to enable linter when fixed everywhere

[ivankatliarchuk]

label := fmt.Sprintf("service/%s/%s", namespace, serviceName)
for _, ep := range endpoints {
ep.Labels[endpoint.ResourceLabelKey] = label
}

[ivankatliarchuk]

name = strings.TrimSuffix(strings.TrimSpace(name), ".")

[ivankatliarchuk]

I wrote a simple test for this function, is the result correct

func TestTagsToAnnotations_Simple(t *testing.T) {
	ns := &nomadServiceSource{}
	tags := []string{
		"external-dns.foo=bar",
		"external-dns.ttl=60",
		"external-dns=controller",
		"invalid-tag",
		"external-dns.foo", // missing '='
	}
	expected := map[string]string{
		"external-dns.alpha.kubernetes.io/foo":          "bar",
		"external-dns.alpha.kubernetes.io/ttl":          "60",
		"external-dns.alpha.kubernetes.io/external-dns": "controller",
	}
	result := ns.tagsToAnnotations(tags)
	assert.Equal(t, expected, result)
}

[k8s-ci-robot]

PR needs rebase.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.