agent: add option to disable agent cache for HTTP endpoints (#8023)

This allows the operator to disable agent caching for the http endpoint.
It is on by default for backwards compatibility and if disabled will
ignore the url parameter `cached`.

Author: hanshasselberg

agent/catalog_endpoint.go

@@ -84,7 +84,7 @@ func (s *HTTPServer) CatalogDatacenters(resp http.ResponseWriter, req *http.Requ
 	parseCacheControl(resp, req, &args.QueryOptions)
 	var out []string
 
-	if args.QueryOptions.UseCache {
+	if s.agent.config.HTTPUseCache && args.QueryOptions.UseCache {
 		raw, m, err := s.agent.cache.Get(cachetype.CatalogDatacentersName, &args)
 		if err != nil {
 			metrics.IncrCounterWithLabels([]string{"client", "rpc", "error", "catalog_datacenters"}, 1,
@@ -166,7 +166,7 @@ func (s *HTTPServer) CatalogServices(resp http.ResponseWriter, req *http.Request
 	var out structs.IndexedServices
 	defer setMeta(resp, &out.QueryMeta)
 
-	if args.QueryOptions.UseCache {
+	if s.agent.config.HTTPUseCache && args.QueryOptions.UseCache {
 		raw, m, err := s.agent.cache.Get(cachetype.CatalogListServicesName, &args)
 		if err != nil {
 			metrics.IncrCounterWithLabels([]string{"client", "rpc", "error", "catalog_services"}, 1,
@@ -255,7 +255,7 @@ func (s *HTTPServer) catalogServiceNodes(resp http.ResponseWriter, req *http.Req
 	var out structs.IndexedServiceNodes
 	defer setMeta(resp, &out.QueryMeta)
 
-	if args.QueryOptions.UseCache {
+	if s.agent.config.HTTPUseCache && args.QueryOptions.UseCache {
 		raw, m, err := s.agent.cache.Get(cachetype.CatalogServicesName, &args)
 		if err != nil {
 			metrics.IncrCounterWithLabels([]string{"client", "rpc", "error", "catalog_service_nodes"}, 1,

agent/config/builder.go

@@ -835,6 +835,7 @@ func (b *Builder) Build() (rt RuntimeConfig, err error) {
 		HTTPBlockEndpoints:  c.HTTPConfig.BlockEndpoints,
 		HTTPResponseHeaders: c.HTTPConfig.ResponseHeaders,
 		AllowWriteHTTPFrom:  b.cidrsVal("allow_write_http_from", c.HTTPConfig.AllowWriteHTTPFrom),
+		HTTPUseCache:        b.boolValWithDefault(c.HTTPConfig.UseCache, true),
 
 		// Telemetry
 		Telemetry: lib.TelemetryConfig{

agent/config/config.go

@@ -641,6 +641,7 @@ type HTTPConfig struct {
 	BlockEndpoints     []string          `json:"block_endpoints,omitempty" hcl:"block_endpoints" mapstructure:"block_endpoints"`
 	AllowWriteHTTPFrom []string          `json:"allow_write_http_from,omitempty" hcl:"allow_write_http_from" mapstructure:"allow_write_http_from"`
 	ResponseHeaders    map[string]string `json:"response_headers,omitempty" hcl:"response_headers" mapstructure:"response_headers"`
+	UseCache           *bool             `json:"use_cache,omitempty" hcl:"use_cache" mapstructure:"use_cache"`
 }
 
 type Performance struct {

agent/config/runtime.go

@@ -349,6 +349,12 @@ type RuntimeConfig struct {
 	// hcl: dns_config { cache_max_age = "duration" }
 	DNSCacheMaxAge time.Duration
 
+	// HTTPUseCache whether or not to use cache for http queries. Defaults
+	// to true.
+	//
+	// hcl: http_config { use_cache = (true|false) }
+	HTTPUseCache bool
+
 	// HTTPBlockEndpoints is a list of endpoint prefixes to block in the
 	// HTTP API. Any requests to these will get a 403 response.
 	//

agent/config/runtime_test.go

@@ -2075,6 +2075,54 @@ func TestConfigFlagsAndEdgecases(t *testing.T) {
 				`},
 			err: "Serf Advertise WAN address 10.0.0.1:1000 already configured for RPC Advertise",
 		},
+		{
+			desc: "http use_cache defaults to true",
+			args: []string{
+				`-data-dir=` + dataDir,
+			},
+			json: []string{`{
+				"http_config": {}
+			}`},
+			hcl: []string{`
+				http_config = {}
+			`},
+			patch: func(rt *RuntimeConfig) {
+				rt.DataDir = dataDir
+				rt.HTTPUseCache = true
+			},
+		},
+		{
+			desc: "http use_cache is enabled when true",
+			args: []string{
+				`-data-dir=` + dataDir,
+			},
+			json: []string{`{
+				"http_config": { "use_cache": true }
+			}`},
+			hcl: []string{`
+				http_config = { use_cache = true }
+			`},
+			patch: func(rt *RuntimeConfig) {
+				rt.DataDir = dataDir
+				rt.HTTPUseCache = true
+			},
+		},
+		{
+			desc: "http use_cache is disabled when false",
+			args: []string{
+				`-data-dir=` + dataDir,
+			},
+			json: []string{`{
+				"http_config": { "use_cache": false }
+			}`},
+			hcl: []string{`
+				http_config = { use_cache = false }
+			`},
+			patch: func(rt *RuntimeConfig) {
+				rt.DataDir = dataDir
+				rt.HTTPUseCache = false
+			},
+		},
 		{
 			desc: "sidecar_service can't have ID",
 			args: []string{
@@ -4134,7 +4182,8 @@ func TestFullConfig(t *testing.T) {
 				"response_headers": {
 					"M6TKa9NP": "xjuxjOzQ",
 					"JRCrHZed": "rl0mTx81"
-				}
+				},
+				"use_cache": false
 			},
 			"key_file": "IEkkwgIA",
 			"leave_on_terminate": true,
@@ -4772,6 +4821,7 @@ func TestFullConfig(t *testing.T) {
 					"M6TKa9NP" = "xjuxjOzQ"
 					"JRCrHZed" = "rl0mTx81"
 				}
+				use_cache = false
 			}
 			key_file = "IEkkwgIA"
 			leave_on_terminate = true
@@ -5486,6 +5536,7 @@ func TestFullConfig(t *testing.T) {
 		HTTPMaxConnsPerClient:                  100,
 		HTTPSHandshakeTimeout:                  2391 * time.Millisecond,
 		HTTPSPort:                              15127,
+		HTTPUseCache:                           false,
 		KeyFile:                                "IEkkwgIA",
 		KVMaxValueSize:                         1234567800000000,
 		LeaveDrainTime:                         8265 * time.Second,
@@ -6368,6 +6419,7 @@ func TestSanitize(t *testing.T) {
 		"HTTPMaxConnsPerClient": 0,
 		"HTTPPort": 0,
 		"HTTPResponseHeaders": {},
+		"HTTPUseCache": false,
 		"HTTPSAddrs": [],
 		"HTTPSHandshakeTimeout": "0s",
 		"HTTPSPort": 0,

agent/discovery_chain_endpoint.go

@@ -59,7 +59,7 @@ func (s *HTTPServer) DiscoveryChainRead(resp http.ResponseWriter, req *http.Requ
 	var out structs.DiscoveryChainResponse
 	defer setMeta(resp, &out.QueryMeta)
 
-	if args.QueryOptions.UseCache {
+	if s.agent.config.HTTPUseCache && args.QueryOptions.UseCache {
 		raw, m, err := s.agent.cache.Get(cachetype.CompiledDiscoveryChainName, &args)
 		if err != nil {
 			return nil, err

agent/health_endpoint.go

@@ -198,7 +198,7 @@ func (s *HTTPServer) healthServiceNodes(resp http.ResponseWriter, req *http.Requ
 	var out structs.IndexedCheckServiceNodes
 	defer setMeta(resp, &out.QueryMeta)
 
-	if args.QueryOptions.UseCache {
+	if s.agent.config.HTTPUseCache && args.QueryOptions.UseCache {
 		raw, m, err := s.agent.cache.Get(cachetype.HealthServicesName, &args)
 		if err != nil {
 			return nil, err

agent/prepared_query_endpoint.go

@@ -121,7 +121,7 @@ func (s *HTTPServer) preparedQueryExecute(id string, resp http.ResponseWriter, r
 	var reply structs.PreparedQueryExecuteResponse
 	defer setMeta(resp, &reply.QueryMeta)
 
-	if args.QueryOptions.UseCache {
+	if s.agent.config.HTTPUseCache && args.QueryOptions.UseCache {
 		raw, m, err := s.agent.cache.Get(cachetype.PreparedQueryName, &args)
 		if err != nil {
 			// Don't return error if StaleIfError is set and we are within it and had

website/pages/docs/agent/options.mdx

@@ -1405,6 +1405,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'."
 
   - `allow_write_http_from` This object is a list of networks in CIDR notation (eg "127.0.0.0/8") that are allowed to call the agent write endpoints. It defaults to an empty list, which means all networks are allowed. This is used to make the agent read-only, except for select ip ranges. - To block write calls from anywhere, use `[ "255.255.255.255/32" ]`. - To only allow write calls from localhost, use `[ "127.0.0.0/8" ]` - To only allow specific IPs, use `[ "10.0.0.1/32", "10.0.0.2/32" ]`
 
+  - `use_cache` Defaults to true. If disabled, the agent won't be using [agent caching](/api/features/caching) to answer the request. Even when the url parameter is provided.
+
 - `leave_on_terminate` If enabled, when the agent receives a TERM signal, it will send a `Leave` message to the rest of the cluster and gracefully leave. The default behavior for this feature varies based on whether or not the agent is running as a client or a server (prior to Consul 0.7 the default value was unconditionally set to `false`). On agents in client-mode, this defaults to `true` and for agents in server-mode, this defaults to `false`.
 
 - `limits` Available in Consul 0.9.3 and later, this is a nested