Remove support for max_concurrency and max_queue_length for Async APIs

Author: deliahu

docs/workloads/async/autoscaling.md

@@ -4,14 +4,6 @@ Cortex auto-scales AsyncAPIs on a per-API basis based on your configuration.
 
 ## Autoscaling replicas
 
-### Relevant pod configuration
-
-In addition to the autoscaling configuration options (described below), there is one field in the pod configuration which are relevant to replica autoscaling:
-
-**`max_concurrency`** (default: 1): The maximum number of requests that will be concurrently sent into the container by Cortex. If your web server is designed to handle multiple concurrent requests, increasing `max_concurrency` will increase the throughput of a replica (and result in fewer total replicas for a given load).
-
-<br>
-
 ### Autoscaling configuration
 
 **`min_replicas`**: The lower bound on how many replicas can be running for an API.
@@ -22,13 +14,13 @@ In addition to the autoscaling configuration options (described below), there is
 
 <br>
 
-**`target_in_flight`** (default: `max_concurrency` in the pod configuration): This is the desired number of in-flight requests per replica, and is the metric which the autoscaler uses to make scaling decisions. The number of in-flight requests is simply how many requests have been submitted and are not yet finished being processed. Therefore, this number includes requests which are actively being processed as well as requests which are waiting in the queue.
+**`target_in_flight`** (default: 1): This is the desired number of in-flight requests per replica, and is the metric which the autoscaler uses to make scaling decisions. The number of in-flight requests is simply how many requests have been submitted and are not yet finished being processed. Therefore, this number includes requests which are actively being processed as well as requests which are waiting in the queue.
 
 The autoscaler uses this formula to determine the number of desired replicas:
 
 `desired replicas = total in-flight requests / target_in_flight`
 
-For example, setting `target_in_flight` to `max_concurrency` (the default) causes the cluster to adjust the number of replicas so that on average, there are no requests waiting in the queue.
+For example, setting `target_in_flight` to 1 (the default) causes the cluster to adjust the number of replicas so that on average, there are no requests waiting in the queue.
 
 <br>
 
@@ -66,9 +58,9 @@ Cortex spins up and down instances based on the aggregate resource requests of a
 
 ## Overprovisioning
 
-The default value for `target_in_flight` is `max_concurrency`, which behaves well in many situations (see above for an explanation of how `target_in_flight` affects autoscaling). However, if your application is sensitive to spikes in traffic or if creating new replicas takes too long (see below), you may find it helpful to maintain extra capacity to handle the increased traffic while new replicas are being created. This can be accomplished by setting `target_in_flight` to a lower value relative to the expected replica's concurrency. The smaller `target_in_flight` is, the more unused capacity your API will have, and the more room it will have to handle sudden increased load. The increased request rate will still trigger the autoscaler, and your API will stabilize again (maintaining the overprovisioned capacity).
+The default value for `target_in_flight` is 1, which behaves well in many situations (see above for an explanation of how `target_in_flight` affects autoscaling). However, if your application is sensitive to spikes in traffic or if creating new replicas takes too long (see below), you may find it helpful to maintain extra capacity to handle the increased traffic while new replicas are being created. This can be accomplished by setting `target_in_flight` to a lower value. The smaller `target_in_flight` is, the more unused capacity your API will have, and the more room it will have to handle sudden increased load. The increased request rate will still trigger the autoscaler, and your API will stabilize again (maintaining the overprovisioned capacity).
 
-For example, if you've determined that each replica in your API can handle 2 concurrent requests, you would typically set `target_in_flight` to 2. In a scenario where your API is receiving 8 concurrent requests on average, the autoscaler would maintain 4 live replicas (8/2 = 4). If you wanted to overprovision by 25%, you could set `target_in_flight` to 1.6, causing the autoscaler maintain 5 live replicas (8/1.6 = 5).
+For example, if you wanted to overprovision by 25%, you could set `target_in_flight` to 0.8. If your API has an average of 4 concurrent requests, the autoscaler would maintain 5 live replicas (4/0.8 = 5).
 
 ## Autoscaling responsiveness
 

docs/workloads/async/configuration.md

@@ -5,7 +5,6 @@
   kind: AsyncAPI  # must be "AsyncAPI" for async APIs (required)
   pod:  # pod configuration (required)
     port: <int>  # port to which requests will be sent (default: 8080; exported as $CORTEX_PORT)
-    max_concurrency: <int>  # maximum number of requests that will be concurrently sent into the container (default: 1)
     containers:  # configurations for the containers to run (at least one constainer must be provided)
       - name: <string>  # name of the container (required)
         image: <string>  # docker image to use for the container (required)
@@ -46,7 +45,7 @@
     min_replicas: <int>  # minimum number of replicas (default: 1)
     max_replicas: <int>  # maximum number of replicas (default: 100)
     init_replicas: <int>  # initial number of replicas (default: <min_replicas>)
-    target_in_flight: <int>  # desired number of in-flight requests per replica (including requests actively being processed as well as queued), which the autoscaler tries to maintain (default: <max_concurrency>)
+    target_in_flight: <int>  # desired number of in-flight requests per replica (including requests actively being processed as well as queued), which the autoscaler tries to maintain (default: 1)
     window: <duration>  # duration over which to average the API's in-flight requests per replica (default: 60s)
     downscale_stabilization_period: <duration>  # the API will not scale below the highest recommendation made during this period (default: 5m)
     upscale_stabilization_period: <duration>  # the API will not scale above the lowest recommendation made during this period (default: 1m)

pkg/types/spec/validations.go

@@ -141,7 +141,7 @@ func multiAPIsValidation() *cr.StructFieldValidation {
 }
 
 func podValidation(kind userconfig.Kind) *cr.StructFieldValidation {
-	return &cr.StructFieldValidation{
+	validation := &cr.StructFieldValidation{
 		StructField: "Pod",
 		StructValidation: &cr.StructValidation{
 			StructFieldValidations: []*cr.StructFieldValidation{
@@ -180,30 +180,37 @@ func podValidation(kind userconfig.Kind) *cr.StructFieldValidation {
 						},
 					},
 				},
-				{
-					StructField: "MaxQueueLength",
-					Int64Validation: &cr.Int64Validation{
-						Default:     consts.DefaultMaxQueueLength,
-						GreaterThan: pointer.Int64(0),
-						// the proxy can theoretically accept up to 32768 connections, but during testing,
-						// it has been observed that the number is just slightly lower, so it has been offset by 2678
-						LessThanOrEqualTo: pointer.Int64(30000),
-					},
-				},
-				{
-					StructField: "MaxConcurrency",
-					Int64Validation: &cr.Int64Validation{
-						Default:     consts.DefaultMaxConcurrency,
-						GreaterThan: pointer.Int64(0),
-						// the proxy can theoretically accept up to 32768 connections, but during testing,
-						// it has been observed that the number is just slightly lower, so it has been offset by 2678
-						LessThanOrEqualTo: pointer.Int64(30000),
-					},
-				},
 				containersValidation(kind),
 			},
 		},
 	}
+
+	if kind == userconfig.RealtimeAPIKind {
+		validation.StructValidation.StructFieldValidations = append(validation.StructValidation.StructFieldValidations,
+			&cr.StructFieldValidation{
+				StructField: "MaxQueueLength",
+				Int64Validation: &cr.Int64Validation{
+					Default:     consts.DefaultMaxQueueLength,
+					GreaterThan: pointer.Int64(0),
+					// the proxy can theoretically accept up to 32768 connections, but during testing,
+					// it has been observed that the number is just slightly lower, so it has been offset by 2678
+					LessThanOrEqualTo: pointer.Int64(30000),
+				},
+			},
+			&cr.StructFieldValidation{
+				StructField: "MaxConcurrency",
+				Int64Validation: &cr.Int64Validation{
+					Default:     consts.DefaultMaxConcurrency,
+					GreaterThan: pointer.Int64(0),
+					// the proxy can theoretically accept up to 32768 connections, but during testing,
+					// it has been observed that the number is just slightly lower, so it has been offset by 2678
+					LessThanOrEqualTo: pointer.Int64(30000),
+				},
+			},
+		)
+	}
+
+	return validation
 }
 
 func containersValidation(kind userconfig.Kind) *cr.StructFieldValidation {
@@ -807,12 +814,19 @@ func validateAutoscaling(api *userconfig.API) error {
 	autoscaling := api.Autoscaling
 	pod := api.Pod
 
-	if autoscaling.TargetInFlight == nil {
-		autoscaling.TargetInFlight = pointer.Float64(float64(pod.MaxConcurrency))
+	if api.Kind == userconfig.RealtimeAPIKind {
+		if autoscaling.TargetInFlight == nil {
+			autoscaling.TargetInFlight = pointer.Float64(float64(pod.MaxConcurrency))
+		}
+		if *autoscaling.TargetInFlight > float64(pod.MaxConcurrency)+float64(pod.MaxQueueLength) {
+			return ErrorTargetInFlightLimitReached(*autoscaling.TargetInFlight, pod.MaxConcurrency, pod.MaxQueueLength)
+		}
 	}
 
-	if *autoscaling.TargetInFlight > float64(pod.MaxConcurrency)+float64(pod.MaxQueueLength) {
-		return ErrorTargetInFlightLimitReached(*autoscaling.TargetInFlight, pod.MaxConcurrency, pod.MaxQueueLength)
+	if api.Kind == userconfig.AsyncAPIKind {
+		if autoscaling.TargetInFlight == nil {
+			autoscaling.TargetInFlight = pointer.Float64(1)
+		}
 	}
 
 	if autoscaling.MinReplicas > autoscaling.MaxReplicas {

pkg/types/userconfig/api.go

@@ -153,7 +153,7 @@ func IdentifyAPI(filePath string, name string, kind Kind, index int) string {
 func (api *API) ToK8sAnnotations() map[string]string {
 	annotations := map[string]string{}
 
-	if api.Pod != nil {
+	if api.Pod != nil && api.Kind == RealtimeAPIKind {
 		annotations[MaxConcurrencyAnnotationKey] = s.Int64(api.Pod.MaxConcurrency)
 		annotations[MaxQueueLengthAnnotationKey] = s.Int64(api.Pod.MaxQueueLength)
 	}
@@ -257,7 +257,7 @@ func (api *API) UserStr() string {
 
 	if api.Pod != nil {
 		sb.WriteString(fmt.Sprintf("%s:\n", PodKey))
-		sb.WriteString(s.Indent(api.Pod.UserStr(), "  "))
+		sb.WriteString(s.Indent(api.Pod.UserStr(api.Kind), "  "))
 	}
 
 	if api.Networking != nil {
@@ -286,7 +286,7 @@ func (trafficSplit *TrafficSplit) UserStr() string {
 	return sb.String()
 }
 
-func (pod *Pod) UserStr() string {
+func (pod *Pod) UserStr(kind Kind) string {
 	var sb strings.Builder
 
 	if pod.ShmSize != nil {
@@ -301,8 +301,10 @@ func (pod *Pod) UserStr() string {
 		sb.WriteString(fmt.Sprintf("%s: %d\n", PortKey, *pod.Port))
 	}
 
-	sb.WriteString(fmt.Sprintf("%s: %s\n", MaxConcurrencyKey, s.Int64(pod.MaxConcurrency)))
-	sb.WriteString(fmt.Sprintf("%s: %s\n", MaxQueueLengthKey, s.Int64(pod.MaxQueueLength)))
+	if kind == RealtimeAPIKind {
+		sb.WriteString(fmt.Sprintf("%s: %s\n", MaxConcurrencyKey, s.Int64(pod.MaxConcurrency)))
+		sb.WriteString(fmt.Sprintf("%s: %s\n", MaxQueueLengthKey, s.Int64(pod.MaxQueueLength)))
+	}
 
 	sb.WriteString(fmt.Sprintf("%s:\n", ContainersKey))
 	for _, container := range pod.Containers {