From b7443366b3c3b84cfb80c9f7e8e4555edfd7c9ca Mon Sep 17 00:00:00 2001 From: Knative Prow Robot Date: Wed, 8 Jun 2022 07:54:38 -0700 Subject: [PATCH] [release-1.2] Add per-revision examples to serving config (#5023) * Add per-revision examples to serving config * make global config first tab, clean up formatting * some updates for revision configs * update option for Operator * re-add config map setting * updates from SME * minor updates Co-authored-by: Ashleigh Brennan --- docs/serving/configuration/config-defaults.md | 611 +++++++++++------- 1 file changed, 389 insertions(+), 222 deletions(-) diff --git a/docs/serving/configuration/config-defaults.md b/docs/serving/configuration/config-defaults.md index a90ce788f..e1b21803b 100644 --- a/docs/serving/configuration/config-defaults.md +++ b/docs/serving/configuration/config-defaults.md @@ -5,10 +5,12 @@ The `config-defaults` ConfigMap, known as the Defaults ConfigMap, contains setti This ConfigMap is located in the `knative-serving` namespace. You can view the current `config-defaults` ConfigMap by running the following command: + ```yaml kubectl get configmap -n knative-serving config-defaults -oyaml ``` ## Example config-defaults ConfigMap + ```yaml apiVersion: v1 kind: ConfigMap @@ -30,319 +32,484 @@ data: allow-container-concurrency-zero: "true" enable-service-links: "false" ``` + See below for a description of each property. + ## Properties -### Revision Timeout Seconds + +### Revision timeout seconds {% raw %} -revision-timeout-seconds contains the default number of -seconds to use for the revision's per-request timeout, if -none is specified. +The revision timeout value determines the default number of seconds to use for the revision's per-request timeout if none is specified. {% endraw %} -**Key**: `revision-timeout-seconds` - -**Default**: `"300"` (5 minutes) +* **Global key:** `revision-timeout-seconds` +* **Per-revision annotation key:** `timeout` +* **Possible values:** integer +* **Default:** `"300"` (5 minutes) **Example:** -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-defaults - namespace: knative-serving -data: - revision-timeout-seconds: "300" # 5 minutes -``` -### Max Revision Timeout Seconds +=== "Global (ConfigMap)" + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-defaults + namespace: knative-serving + data: + revision-timeout-seconds: "300" + ``` + +=== "Per Revision" + ```yaml + apiVersion: serving.knative.dev/v1 + kind: Service + metadata: + name: helloworld-go + namespace: default + spec: + template: + spec: + timeout: 300 + containers: + - image: gcr.io/knative-samples/helloworld-go + ``` + +### Max revision timeout seconds {% raw %} -max-revision-timeout-seconds contains the maximum number of -seconds that can be used for revision-timeout-seconds. -This value must be greater than or equal to revision-timeout-seconds. -If omitted, the system default is used (600 seconds). +The `max-revision-timeout-seconds` value determines the maximum number of seconds that can be used for `revision-timeout-seconds`. This value must be greater than or equal to `revision-timeout-seconds`. If omitted, the system default is used (600 seconds). -If this value is increased, the activator's terminationGraceTimeSeconds -should also be increased to prevent in-flight requests being disrupted. +If this value is increased, the activator's `terminationGraceTimeSeconds` should also be increased to prevent in-flight requests from being disrupted. {% endraw %} -**Key**: `max-revision-timeout-seconds` - -**Default**: `"600"` (10 minutes) +* **Global key:** `max-revision-timeout-seconds` +* **Per-revision annotation key:** N/A +* **Possible values:** integer +* **Default:** `"600"` (10 minutes) **Example:** -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-defaults - namespace: knative-serving -data: - max-revision-timeout-seconds: "600" # 10 minutes -``` -### Revision Cpu Request +=== "Global (ConfigMap)" + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-defaults + namespace: knative-serving + data: + max-revision-timeout-seconds: "600" + ``` + +### Revision CPU request {% raw %} -revision-cpu-request contains the cpu allocation to assign -to revisions by default. If omitted, no value is specified -and the system default is used. -Below is an example of setting revision-cpu-request. -By default, it is not set by Knative. +The `revision-cpu-request` value determines the CPU allocation assigned to revisions by default. If this value is omitted, the system default is used. This key is not enabled by default for Knative. {% endraw %} -**Key**: `revision-cpu-request` - -**Default**: `"400m"` (0.4 of a CPU (aka 400 milli-CPU)) +* **Global key:** `revision-cpu-request` +* **Per-revision annotation key:** `cpu` +* **Possible values:** integer +* **Default:** `"400m"` (0.4 of a CPU, or 400 milli-CPU) **Example:** -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-defaults - namespace: knative-serving -data: - revision-cpu-request: "400m" # 0.4 of a CPU (aka 400 milli-CPU) -``` -### Revision Memory Request +=== "Global (ConfigMap)" + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-defaults + namespace: knative-serving + data: + revision-cpu-request: "400m" + ``` + +=== "Per Revision" + ```yaml + apiVersion: serving.knative.dev/v1 + kind: Service + metadata: + name: helloworld-go + namespace: default + spec: + template: + spec: + containers: + - image: gcr.io/knative-samples/helloworld-go + resources: + requests: + cpu: "400m" + ``` + +### Revision memory request {% raw %} -revision-memory-request contains the memory allocation to assign -to revisions by default. If omitted, no value is specified -and the system default is used. -Below is an example of setting revision-memory-request. -By default, it is not set by Knative. +The `revision-memory-request` value determines the memory allocation assigned +to revisions by default. If this value is omitted, the system default is used. This key is not enabled by default for Knative. {% endraw %} -**Key**: `revision-memory-request` - -**Default**: `"100M"` (100 megabytes of memory) +* **Global key:** `revision-memory-request` +* **Per-revision annotation key:** `memory` +* **Possible values:** integer +* **Default:** `"100M"` (100 megabytes of memory) **Example:** -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-defaults - namespace: knative-serving -data: - revision-memory-request: "100M" # 100 megabytes of memory -``` + +=== "Global (ConfigMap)" + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-defaults + namespace: knative-serving + data: + revision-memory-request: "100M" + ``` + +=== "Per Revision" + ```yaml + apiVersion: serving.knative.dev/v1 + kind: Service + metadata: + name: helloworld-go + namespace: default + spec: + template: + spec: + containers: + - image: gcr.io/knative-samples/helloworld-go + resources: + requests: + memory: "100M" + ``` ### Revision Ephemeral Storage Request {% raw %} -revision-ephemeral-storage-request contains the ephemeral storage -allocation to assign to revisions by default. If omitted, no value is -specified and the system default is used. +The `revision-ephemeral-storage-request` value determines the ephemeral storage +allocation assigned to revisions by default. If this value is omitted, the system default is used. This key is not enabled by default for Knative. {% endraw %} -**Key**: `revision-ephemeral-storage-request` - -**Default**: `"500M"` (500 megabytes of storage) +* **Global key:** `revision-ephemeral-storage-request` +* **Per-revision annotation key:** `ephemeral-storage` +* **Possible values:** integer +* **Default:** `"500M"` (500 megabytes of storage) **Example:** -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-defaults - namespace: knative-serving -data: - revision-ephemeral-storage-request: "500M" # 500 megabytes of storage -``` -### Revision Cpu Limit +=== "Global (ConfigMap)" + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-defaults + namespace: knative-serving + data: + revision-ephemeral-storage-request: "500M" + ``` + +=== "Per Revision" + ```yaml + apiVersion: serving.knative.dev/v1 + kind: Service + metadata: + name: helloworld-go + namespace: default + spec: + template: + spec: + containers: + - image: gcr.io/knative-samples/helloworld-go + resources: + requests: + ephemeral-storage: "500M" + ``` + +### Revision CPU limit {% raw %} -revision-cpu-limit contains the cpu allocation to limit -revisions to by default. If omitted, no value is specified -and the system default is used. -Below is an example of setting revision-cpu-limit. -By default, it is not set by Knative. +The `revision-cpu-limit` value determines the default CPU allocation limit for revisions. If this value is omitted, the system default is used. This key is not enabled by default for Knative. {% endraw %} -**Key**: `revision-cpu-limit` - -**Default**: `"1000m"` (1 CPU (aka 1000 milli-CPU)) +* **Global key:** `revision-cpu-limit` +* **Per-revision annotation key:** `cpu` +* **Possible values:** integer +* **Default:** `"1000m"` (1 CPU, or 1000 milli-CPU) **Example:** -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-defaults - namespace: knative-serving -data: - revision-cpu-limit: "1000m" # 1 CPU (aka 1000 milli-CPU) -``` -### Revision Memory Limit +=== "Global (ConfigMap)" + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-defaults + namespace: knative-serving + data: + revision-cpu-limit: "1000m" + ``` + +=== "Per Revision" + ```yaml + apiVersion: serving.knative.dev/v1 + kind: Service + metadata: + name: helloworld-go + namespace: default + spec: + template: + spec: + containers: + - image: gcr.io/knative-samples/helloworld-go + resources: + requests: + cpu: "1000m" + ``` + +### Revision memory limit {% raw %} -revision-memory-limit contains the memory allocation to limit -revisions to by default. If omitted, no value is specified -and the system default is used. -Below is an example of setting revision-memory-limit. -By default, it is not set by Knative. +The `revision-memory-limit` value determines the default memory allocation limit for revisions. If this value is omitted, the system default is used. This key is not enabled by default for Knative. {% endraw %} -**Key**: `revision-memory-limit` - -**Default**: `"200M"` (200 megabytes of memory) +* **Global key:** `revision-memory-limit` +* **Per-revision annotation key:** `memory` +* **Possible values:** integer +* **Default:** `"200M"` (200 megabytes of memory) **Example:** -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-defaults - namespace: knative-serving -data: - revision-memory-limit: "200M" # 200 megabytes of memory -``` + +=== "Global (ConfigMap)" + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-defaults + namespace: knative-serving + data: + revision-memory-limit: "200M" + ``` + +=== "Per Revision" + ```yaml + apiVersion: serving.knative.dev/v1 + kind: Service + metadata: + name: helloworld-go + namespace: default + spec: + template: + spec: + containers: + - image: gcr.io/knative-samples/helloworld-go + resources: + requests: + memory: "200M" + ``` ### Revision Ephemeral Storage Limit {% raw %} -revision-ephemeral-storage-limit contains the ephemeral storage -allocation to limit revisions to by default. If omitted, no value is -specified and the system default is used. +The `revision-ephemeral-storage-limit` value determines the default ephemeral storage limit allocated to revisions. If this value is omitted, the system default is used. This key is not enabled by default for Knative. {% endraw %} -**Key**: `revision-ephemeral-storage-limit` - -**Default**: `"750M"` (750 megabytes of storage) +* **Global key:** `revision-ephemeral-storage-limit` +* **Per-revision annotation key:** `ephemeral-storage` +* **Possible values:** integer +* **Default:** `"750M"` (750 megabytes of storage) **Example:** -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-defaults - namespace: knative-serving -data: - revision-ephemeral-storage-limit: "750M" # 750 megabytes of storage -``` -### Container Name Template +=== "Global (ConfigMap)" + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-defaults + namespace: knative-serving + data: + revision-ephemeral-storage-limit: "750M" + ``` + +=== "Per Revision" + ```yaml + apiVersion: serving.knative.dev/v1 + kind: Service + metadata: + name: helloworld-go + namespace: default + spec: + template: + spec: + containers: + - image: gcr.io/knative-samples/helloworld-go + resources: + requests: + ephemeral-storage: "750M" + ``` + +### Container name template {% raw %} -container-name-template contains a template for the default -container name, if none is specified. This field supports -Go templating and is supplied with the ObjectMeta of the -enclosing Service or Configuration, so values such as -{{.Name}} are also valid. +The `container-name-template` value provides a template for the default +container name if no container name is specified. This field supports Go templating and is supplied by the `ObjectMeta` of the enclosing Service or Configuration, so values such as `{{.Name}}` are also valid. {% endraw %} -**Key**: `container-name-template` - -**Default**: `"user-container"` +* **Global key:** `container-name-template` +* **Per-revision annotation key:** `name` +* **Possible values:** string +* **Default:** `"user-container"` **Example:** -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-defaults - namespace: knative-serving -data: - container-name-template: "user-container" -``` -### Container Concurrency +=== "Global (ConfigMap)" + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-defaults + namespace: knative-serving + data: + container-name-template: "user-container" + ``` + +=== "Per Revision" + ```yaml + apiVersion: serving.knative.dev/v1 + kind: Service + metadata: + name: helloworld-go + namespace: default + spec: + template: + spec: + containers: + - name: user-container + image: gcr.io/knative-samples/helloworld-go + ``` + +### Container concurrency {% raw %} -container-concurrency specifies the maximum number -of requests the Container can handle at once, and requests -above this threshold are queued. Setting a value of zero -disables this throttling and lets through as many requests as +The `container-concurrency` value specifies the maximum number of requests the container can handle at once. Requests above this threshold are queued. Setting a value of zero disables this throttling and lets through as many requests as the pod receives. {% endraw %} -**Key**: `container-concurrency` - -**Default**: `"0"` +* **Global key:** `container-concurrency` +* **Per-revision spec key:** `containerConcurrency` +* **Possible values:** integer +* **Default:** `"0"` **Example:** -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-defaults - namespace: knative-serving -data: - container-concurrency: "0" -``` -### Container Concurrency Max Limit +=== "Global (ConfigMap)" + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-defaults + namespace: knative-serving + data: + container-concurrency: "0" + ``` + +=== "Per Revision" + ```yaml + apiVersion: serving.knative.dev/v1 + kind: Service + metadata: + name: helloworld-go + namespace: default + spec: + template: + spec: + containerConcurrency: 0 + ``` + +### Container concurrency max limit {% raw %} -The container concurrency max limit is an operator setting ensuring that -the individual revisions cannot have arbitrary large concurrency -values, or autoscaling targets. `container-concurrency` default setting -must be at or below this value. - -Must be greater than 1. +The `container-concurrency-max-limit` setting disables arbitrary large concurrency values, or autoscaling targets, for individual revisions. The `container-concurrency` default setting must be at or below this value. The value of the `container-concurrency-max-limit` setting must be greater than 1. !!! note - Even with this set, a user can choose a `containerConcurrency` value of 0 (unbounded) unless `allow-container-concurrency-zero` is set to "false". + Even with this set, a user can choose a `containerConcurrency` value of zero (unbounded), unless `allow-container-concurrency-zero` is set to `"false"`. {% endraw %} -**Key**: `container-concurrency-max-limit` - -**Default**: `"1000"` +* **Global key:** `container-concurrency-max-limit` +* **Per-revision annotation key:** N/A +* **Possible values:** integer +* **Default:** `"1000"` **Example:** -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-defaults - namespace: knative-serving -data: - container-concurrency-max-limit: "1000" -``` -### Allow Container Concurrency Zero +=== "Global (ConfigMap)" + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-defaults + namespace: knative-serving + data: + container-concurrency-max-limit: "1000" + ``` + +=== "Global (Operator)" + ```yaml + apiVersion: operator.knative.dev/v1beta1 + kind: KnativeServing + metadata: + name: knative-serving + namespace: knative-serving + spec: + config: + defaults: + container-concurrency-max-limit: "1000" + ``` + +### Allow container concurrency zero {% raw %} -allow-container-concurrency-zero controls whether users can -specify 0 (i.e. unbounded) for containerConcurrency. +The `allow-container-concurrency-zero` value determines whether users can +specify `0` (unbounded) for `containerConcurrency`. {% endraw %} -**Key**: `allow-container-concurrency-zero` - -**Default**: `"true"` +* **Global key:** `allow-container-concurrency-zero` +* **Per-revision annotation key:** N/A +* **Possible values:** boolean +* **Default:** `"true"` **Example:** -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-defaults - namespace: knative-serving -data: - allow-container-concurrency-zero: "true" -``` -### Enable Service Links +=== "Global (ConfigMap)" + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-defaults + namespace: knative-serving + data: + allow-container-concurrency-zero: "true" + ``` + +### Enable Service links {% raw %} -enable-service-links specifies the default value used for the enableServiceLinks field of the PodSpec, when it is omitted by the user. See [the Kubernetes Documentation for the enableServiceLinks Feature](https://kubernetes.io/docs/concepts/services-networking/connect-applications-service/#accessing-the-service). +The `enable-service-links` value specifies the default value used for the `enableServiceLinks` field of the `PodSpec` when it is omitted by the user. See [the Kubernetes documentation about the `enableServiceLinks` feature](https://kubernetes.io/docs/concepts/services-networking/connect-applications-service/#accessing-the-service). This is a tri-state flag with possible values of (true|false|default). -In environments with large number of services it is suggested to set this value to `false`. See [serving#8498](https://github.com/knative/serving/issues/8498). +In environments with large number of Services, it is suggested to set this value to `false`. See [serving#8498](https://github.com/knative/serving/issues/8498). {% endraw %} -**Key**: `enable-service-links` - -**Default**: `"false"` +* **Global key:** `enable-service-links` +* **Per-revision annotation key:** N/A +* **Possible values:** `true|false|default` +* **Default:** `"false"` **Example:** -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-defaults - namespace: knative-serving -data: - enable-service-links: "false" -``` + +=== "Global (ConfigMap)" + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: config-defaults + namespace: knative-serving + data: + enable-service-links: "false" + ```