plugin/azure: add refresh directive (#8614)

Brings azure to parity with route53, which already exposes a refresh
directive to control how often zones are re-synced. azure currently
hardcodes this to 1 minute (Run calls h.run(ctx, time.Minute)) with no
way to change it, even though the internal run() method already takes
an arbitrary interval parameter - the plumbing exists, it just wasn't
exposed as a Corefile option.

Adds a refresh field to the Azure struct, threads it through New(), and
has Run() use h.refresh instead of the hardcoded value. Parses the
refresh directive in parse() mirroring route53's exact validation
(accepts a plain number as seconds or a duration string, must be
greater than 0).

Extends TestSetup with refresh coverage (valid duration, valid plain
number, missing arg, non-numeric, zero, negative). Verified it fails
without the setup.go change (unknown property error) and passes with
it.

Signed-off-by: stackedbyaradhya <aradhyaj736@gmail.com>

plugin/azure/README.md

@@ -10,10 +10,10 @@ The azure plugin is useful for serving zones from Microsoft Azure DNS. The *azur
 all the DNS records supported by Azure, viz. A, AAAA, CNAME, MX, NS, PTR, SOA, SRV, and TXT
 record types. NS record type is not supported by azure private DNS.
 
-Zone data is loaded asynchronously after startup and refreshed every minute.
-An unavailable zone or zone-listing error is logged without preventing CoreDNS from
-starting or other configured zones from being updated. Each zone listing,
-including retries and pagination, has a one-minute timeout.
+Zone data is loaded asynchronously after startup and refreshed every minute by default,
+configurable via `refresh`. An unavailable zone or zone-listing error is logged without
+preventing CoreDNS from starting or other configured zones from being updated. Each zone
+listing, including retries and pagination, has a one-minute timeout.
 Configuration and credential initialization errors still prevent startup.
 
 Until a zone has been successfully loaded, queries for it return SERVFAIL unless
@@ -34,6 +34,7 @@ azure RESOURCE_GROUP:ZONE... {
     environment ENVIRONMENT
     fallthrough [ZONES...]
     access private
+    refresh DURATION
 }
 ~~~
 
@@ -52,6 +53,12 @@ azure RESOURCE_GROUP:ZONE... {
 
 *   `access`  specifies if the zone is `public` or `private`. Default is `public`.
 
+*   `refresh` can be used to control how long between record retrievals from Azure DNS. It
+    requires a duration string as a parameter to specify the duration between update cycles.
+    Each update cycle may result in many Azure API calls depending on how many domains use this
+    plugin and how many records are in each. Adjusting the update frequency may help reduce the
+    potential of API throttling by Azure. If not provided the default refresh is 1 minute.
+
 ## Examples
 
 Enable the *azure* plugin with Azure credentials for private zones `example.org`, `example.private`:

plugin/azure/azure.go

@@ -33,6 +33,7 @@ type Azure struct {
 	publicClient  publicdns.RecordSetsClient
 	privateClient privatedns.RecordSetsClient
 	upstream      *upstream.Upstream
+	refresh       time.Duration
 	zMu           sync.RWMutex
 	zones         zones
 	updates       sync.WaitGroup
@@ -42,7 +43,8 @@ type Azure struct {
 }
 
 // New initializes the configured DNS zones without contacting Azure.
-func New(_ctx context.Context, publicClient publicdns.RecordSetsClient, privateClient privatedns.RecordSetsClient, keys map[string][]string, accessMap map[string]string) (*Azure, error) {
+// refresh sets how often the zones are refreshed from Azure DNS.
+func New(_ctx context.Context, publicClient publicdns.RecordSetsClient, privateClient privatedns.RecordSetsClient, keys map[string][]string, accessMap map[string]string, refresh time.Duration) (*Azure, error) {
 	zones := make(map[string][]*zone, len(keys))
 	names := make([]string, 0, len(keys))
 	for resourceGroup, znames := range keys {
@@ -64,13 +66,14 @@ func New(_ctx context.Context, publicClient publicdns.RecordSetsClient, privateC
 		zones:         zones,
 		zoneNames:     names,
 		upstream:      upstream.New(),
+		refresh:       refresh,
 	}, nil
 }
 
 // Run starts initial and periodic zone synchronization in the background.
 func (h *Azure) Run(ctx context.Context) error {
 	h.updates.Go(func() {
-		h.run(ctx, time.Minute)
+		h.run(ctx, h.refresh)
 	})
 	return nil
 }

plugin/azure/setup.go

@@ -2,7 +2,9 @@ package azure
 
 import (
 	"context"
+	"strconv"
 	"strings"
+	"time"
 
 	"github.com/coredns/caddy"
 	"github.com/coredns/coredns/core/dnsserver"
@@ -21,7 +23,7 @@ var log = clog.NewWithPlugin("azure")
 func init() { plugin.Register("azure", setup) }
 
 func setup(c *caddy.Controller) error {
-	env, keys, accessMap, fall, err := parse(c)
+	env, keys, accessMap, fall, refresh, err := parse(c)
 	if err != nil {
 		return plugin.Error("azure", err)
 	}
@@ -39,7 +41,7 @@ func setup(c *caddy.Controller) error {
 		return plugin.Error("azure", err)
 	}
 
-	h, err := New(ctx, publicDNSClient, privateDNSClient, keys, accessMap)
+	h, err := New(ctx, publicDNSClient, privateDNSClient, keys, accessMap, refresh)
 	if err != nil {
 		cancel()
 		return plugin.Error("azure", err)
@@ -59,12 +61,13 @@ func setup(c *caddy.Controller) error {
 	return nil
 }
 
-func parse(c *caddy.Controller) (auth.EnvironmentSettings, map[string][]string, map[string]string, fall.F, error) {
+func parse(c *caddy.Controller) (auth.EnvironmentSettings, map[string][]string, map[string]string, fall.F, time.Duration, error) {
 	resourceGroupMapping := map[string][]string{}
 	accessMap := map[string]string{}
 	resourceGroupSet := map[string]struct{}{}
 	azureEnv := azurerest.PublicCloud
 	env := auth.EnvironmentSettings{Values: map[string]string{}}
+	refresh := time.Duration(1) * time.Minute // default update frequency to 1 minute
 
 	var fall fall.F
 	var access string
@@ -76,14 +79,14 @@ func parse(c *caddy.Controller) (auth.EnvironmentSettings, map[string][]string,
 		for i := range args {
 			parts := strings.SplitN(args[i], ":", 2)
 			if len(parts) != 2 {
-				return env, resourceGroupMapping, accessMap, fall, c.Errf("invalid resource group/zone: %q", args[i])
+				return env, resourceGroupMapping, accessMap, fall, refresh, c.Errf("invalid resource group/zone: %q", args[i])
 			}
 			resourceGroup, zoneName := parts[0], parts[1]
 			if resourceGroup == "" || zoneName == "" {
-				return env, resourceGroupMapping, accessMap, fall, c.Errf("invalid resource group/zone: %q", args[i])
+				return env, resourceGroupMapping, accessMap, fall, refresh, c.Errf("invalid resource group/zone: %q", args[i])
 			}
 			if _, ok := resourceGroupSet[resourceGroup+zoneName]; ok {
-				return env, resourceGroupMapping, accessMap, fall, c.Errf("conflicting zone: %q", args[i])
+				return env, resourceGroupMapping, accessMap, fall, refresh, c.Errf("conflicting zone: %q", args[i])
 			}
 
 			resourceGroupSet[resourceGroup+zoneName] = struct{}{}
@@ -96,52 +99,68 @@ func parse(c *caddy.Controller) (auth.EnvironmentSettings, map[string][]string,
 			switch c.Val() {
 			case "subscription":
 				if !c.NextArg() {
-					return env, resourceGroupMapping, accessMap, fall, c.ArgErr()
+					return env, resourceGroupMapping, accessMap, fall, refresh, c.ArgErr()
 				}
 				env.Values[auth.SubscriptionID] = c.Val()
 			case "tenant":
 				if !c.NextArg() {
-					return env, resourceGroupMapping, accessMap, fall, c.ArgErr()
+					return env, resourceGroupMapping, accessMap, fall, refresh, c.ArgErr()
 				}
 				env.Values[auth.TenantID] = c.Val()
 			case "client":
 				if !c.NextArg() {
-					return env, resourceGroupMapping, accessMap, fall, c.ArgErr()
+					return env, resourceGroupMapping, accessMap, fall, refresh, c.ArgErr()
 				}
 				env.Values[auth.ClientID] = c.Val()
 			case "secret":
 				if !c.NextArg() {
-					return env, resourceGroupMapping, accessMap, fall, c.ArgErr()
+					return env, resourceGroupMapping, accessMap, fall, refresh, c.ArgErr()
 				}
 				env.Values[auth.ClientSecret] = c.Val()
 			case "environment":
 				if !c.NextArg() {
-					return env, resourceGroupMapping, accessMap, fall, c.ArgErr()
+					return env, resourceGroupMapping, accessMap, fall, refresh, c.ArgErr()
 				}
 				var err error
 				if azureEnv, err = azurerest.EnvironmentFromName(c.Val()); err != nil {
-					return env, resourceGroupMapping, accessMap, fall, c.Errf("cannot set azure environment: %q", err.Error())
+					return env, resourceGroupMapping, accessMap, fall, refresh, c.Errf("cannot set azure environment: %q", err.Error())
 				}
 			case "fallthrough":
 				fall.SetZonesFromArgs(c.RemainingArgs())
 			case "access":
 				if !c.NextArg() {
-					return env, resourceGroupMapping, accessMap, fall, c.ArgErr()
+					return env, resourceGroupMapping, accessMap, fall, refresh, c.ArgErr()
 				}
 				access = c.Val()
 				if access != "public" && access != "private" {
-					return env, resourceGroupMapping, accessMap, fall, c.Errf("invalid access value: can be public/private, found: %s", access)
+					return env, resourceGroupMapping, accessMap, fall, refresh, c.Errf("invalid access value: can be public/private, found: %s", access)
 				}
 				for _, k := range currentZoneKeys {
 					accessMap[k] = access
 				}
+			case "refresh":
+				if !c.NextArg() {
+					return env, resourceGroupMapping, accessMap, fall, refresh, c.ArgErr()
+				}
+				refreshStr := c.Val()
+				_, err := strconv.Atoi(refreshStr)
+				if err == nil {
+					refreshStr += "s"
+				}
+				refresh, err = time.ParseDuration(refreshStr)
+				if err != nil {
+					return env, resourceGroupMapping, accessMap, fall, refresh, c.Errf("unable to parse duration: %v", err)
+				}
+				if refresh <= 0 {
+					return env, resourceGroupMapping, accessMap, fall, refresh, c.Errf("refresh interval must be greater than 0: %q", refreshStr)
+				}
 			default:
-				return env, resourceGroupMapping, accessMap, fall, c.Errf("unknown property: %q", c.Val())
+				return env, resourceGroupMapping, accessMap, fall, refresh, c.Errf("unknown property: %q", c.Val())
 			}
 		}
 	}
 
 	env.Values[auth.Resource] = azureEnv.ResourceManagerEndpoint
 	env.Environment = azureEnv
-	return env, resourceGroupMapping, accessMap, fall, nil
+	return env, resourceGroupMapping, accessMap, fall, refresh, nil
 }

plugin/azure/setup_test.go

@@ -35,6 +35,24 @@ func TestSetup(t *testing.T) {
 }`, false, nil},
 		{`azure resource_set:zone {
     foo
+}`, true, nil},
+		{`azure resource_set:zone {
+    refresh 3m
+}`, false, nil},
+		{`azure resource_set:zone {
+    refresh 30
+}`, false, nil},
+		{`azure resource_set:zone {
+    refresh
+}`, true, nil},
+		{`azure resource_set:zone {
+    refresh abc
+}`, true, nil},
+		{`azure resource_set:zone {
+    refresh 0
+}`, true, nil},
+		{`azure resource_set:zone {
+    refresh -5m
 }`, true, nil},
 		{`azure resource_set:zone {
     tenant tenant_id
@@ -75,7 +93,7 @@ func TestSetup(t *testing.T) {
 
 	for i, test := range tests {
 		c := caddy.NewTestController("dns", test.body)
-		_, _, accessMap, _, err := parse(c)
+		_, _, accessMap, _, _, err := parse(c)
 		if (err == nil) == test.expectedError {
 			t.Fatalf("Unexpected errors: %v in test: %d\n\t%s", err, i, test.body)
 		}

plugin/azure/sync_test.go

@@ -56,7 +56,8 @@ func newTestAzure(t *testing.T, private bool, handle azureAPIHandler) (*Azure, *
 	}
 	h, err := New(context.Background(), publicClient, privateClient,
 		map[string][]string{"rg": {"healthy.example", "missing.example"}},
-		map[string]string{"rghealthy.example": access, "rgmissing.example": access})
+		map[string]string{"rghealthy.example": access, "rgmissing.example": access},
+		time.Minute)
 	if err != nil {
 		t.Fatal(err)
 	}