feat: add isSource template function to scope --fqdn-template by source

[ivankatliarchuk]

What does it do ?

• New case-insensitive template function isSource "name" (matches the exact --source flag value, e.g. "traefik-proxy"), usable in --fqdn-template/--target-template/--fqdn-target-template.
• template.Engine gains WithSource(name), which scopes an engine to one source by cloning its parsed templates and rebinding isSource — avoids re-parsing and avoids mutating a template shared across other sources' engines.
• Docs: new isSource section and function-table entry in docs/advanced/fqdn-templating.md, explaining the source-vs-Kind distinction with a worked example.

Motivation

Adds a way to scope templates to specific sources. Relates #6593

• Users running multiple ExternalDNS sources (service, node, traefik-proxy, ...) with a single --fqdn-template had no way to render different logic per source.
• The existing {{ eq .Kind "Service" }} pattern doesn't work reliably for this: some sources span multiple Kubernetes Kinds under one source name (traefik-proxy → IngressRoute/IngressRouteTCP/IngressRouteUDP; unstructured → arbitrary CRD kinds), so Kind-based conditionals can't cleanly target "this source" as a whole.

Complement a solution like #6611

More

• Yes, this PR title follows Conventional Commits
• Yes, I added unit tests
• Yes, I updated end user documentation accordingly

[kubernetes-prow]

[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 ivankatliarchuk for approval. For more information see the Code Review Process.

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

Details

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

[coveralls]

Coverage Report for CI Build 32010655162

Coverage decreased (-0.008%) to 81.849%

Details

• Coverage decreased (-0.008%) from the base build.
• Patch coverage: No coverable lines changed in this PR.
• 82 coverage regressions across 3 files.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

82 previously-covered lines in 3 files lost coverage.

File	Lines Losing Coverage	Coverage
store.go	41	77.09%
template/engine.go	40	65.75%
integration/toolkit/toolkit.go	1	82.32%

---

Coverage Stats

Relevant Lines:	21459
Covered Lines:	17564
Line Coverage:	81.85%
Coverage Strength:	1453.79 hits per line

---

💛 - Coveralls

[mloiseleur]

Suggested change

	// source is the ExternalDNS source name (e.g. "service", "traefik-proxy") this Engine
	// was scoped to via WithSource. Empty for an unscoped Engine.
	source string

Unless I'm missing something, this parameter is written but never read nor used.

[ivankatliarchuk]

It was assigned, but not used. Pushed change

[mloiseleur]

It may makes unknown source name indistinguishable from "not this source".
Wdyt of adding a validation on this ?
Something like this, in source/template/validate.go:

  func validateIsSourceArgs(tmpl *template.Template, flag string) error {
        unknown := sets.New[string]()
        for _, t := range tmpl.Templates() {
                if t.Tree == nil {
                        continue
                }
                walkCommands(t.Root, func(cmd *parse.CommandNode) {
                        if len(cmd.Args) == 0 {
                                return
                        }
                        id, ok := cmd.Args[0].(*parse.IdentifierNode)
                        if !ok || id.Ident != "isSource" {
                                return
                        }
                        for _, arg := range cmd.Args[1:] {
                                if s, ok := arg.(*parse.StringNode); ok && !types.IsKnown(s.Text) {
                                        unknown.Insert(s.Text)
                                }
                        }
                })
        }
        if len(unknown) == 0 {
                return nil
        }
        return fmt.Errorf("parse %s: isSource: unknown source %q (valid: %s)",
                flag, strings.Join(sets.Sorted(unknown), `", "`), strings.Join(types.All, ", "))
  }

[ivankatliarchuk]

We could validate values, sanitize templates against values. For walkCommands - a correct walk has to recurse into IfNode/RangeNode/WithNode/TemplateNode bodies and nested structs, not just top-level t.Root commands - {{ if eq (isSource "ingres") true }} as example needs to be caught too and many more cases. A shallow walker gives false confidence (validates the easy cases, misses nested ones). I understand the gain, is just looks a bit too complex to correctly resolve.

[ivankatliarchuk]

Added validation directly to the function for now

[mloiseleur]

It's modifying the Config, so it could get stuck on last source name, when called multiples times.
FTM, we are good, but we may need at some point to snapshot & restore on defer

[mloiseleur]

This test compares a hand-copy in types.go to a hand-copy in this file.
Mmmh 🤔
@ivankatliarchuk Maybe we can do better by ensuring we are aligned between the source code and the CLI code. When we add a new source, we definitely do not want to miss to fill the two lists (All in source/types/type.go and the allowedSources in pkg/apis/externaldns/types.go.

It could be something like that in pkg/apis/externaldns/types_test.go:

  func TestAllowedSourcesMatchesSourceTypes(t *testing.T) {
        want := append(slices.Clone(types.All), "empty")
        slices.Sort(want)
        got := slices.Clone(allowedSources)
        slices.Sort(got)
        assert.Equal(t, want, got, "allowedSources and source/types.All have drifted")
  }

@ivankatliarchuk Wdyt ?