From 9258df348b48786af96e407aedff899563952369 Mon Sep 17 00:00:00 2001 From: Ashleigh Brennan Date: Fri, 4 Jun 2021 11:18:45 -0500 Subject: [PATCH] 3710: Move Deployment ConfigMap to admin guide (#3721) --- docs/admin/serving/deployment.md | 108 ++++++++++++++++++ docs/developer/serving/services/deployment.md | 49 -------- docs/serving/tag-resolution.md | 34 +----- mkdocs.yml | 7 +- 4 files changed, 117 insertions(+), 81 deletions(-) create mode 100644 docs/admin/serving/deployment.md delete mode 100644 docs/developer/serving/services/deployment.md diff --git a/docs/admin/serving/deployment.md b/docs/admin/serving/deployment.md new file mode 100644 index 000000000..c992ac9ea --- /dev/null +++ b/docs/admin/serving/deployment.md @@ -0,0 +1,108 @@ +# Configure Deployment resources + +The `config-deployment` ConfigMap, known as the Deployment ConfigMap, contains settings that determine how Kubernetes `Deployment` resources, which back Knative services, are configured. This ConfigMap is located in the `knative-serving` namespace. + +You can view the current `config-deployment` ConfigMap by running the following command: + +```bash +kubectl get configmap -n knative-serving config-deployment -oyaml +``` + +## Example `config-deployment` ConfigMap + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-deployment + namespace: knative-serving + labels: + serving.knative.dev/release: devel + annotations: + knative.dev/example-checksum: "fa67b403" +data: + # This is the Go import path for the binary that is containerized + # and substituted here. + queueSidecarImage: ko://knative.dev/serving/cmd/queue + # List of repositories for which tag to digest resolving should be skipped + registriesSkippingTagResolving: "kind.local,ko.local,dev.local" + # digestResolutionTimeout is the maximum time allowed for an image's + # digests to be resolved. + digestResolutionTimeout: "10s" + # ProgressDeadline is the duration we wait for the deployment to + # be ready before considering it failed. + progressDeadline: "600s" + # queueSidecarCPURequest is the requests.cpu to set for the queue proxy sidecar container. + # If omitted, a default value (currently "25m"), is used. + queueSidecarCPURequest: "25m" + # queueSidecarCPULimit is the limits.cpu to set for the queue proxy sidecar container. + # If omitted, no value is specified and the system default is used. + queueSidecarCPULimit: "1000m" + # queueSidecarMemoryRequest is the requests.memory to set for the queue proxy container. + # If omitted, no value is specified and the system default is used. + queueSidecarMemoryRequest: "400Mi" + # queueSidecarMemoryLimit is the limits.memory to set for the queue proxy container. + # If omitted, no value is specified and the system default is used. + queueSidecarMemoryLimit: "800Mi" + # queueSidecarEphemeralStorageRequest is the requests.ephemeral-storage to + # set for the queue proxy sidecar container. + # If omitted, no value is specified and the system default is used. + queueSidecarEphemeralStorageRequest: "512Mi" + # queueSidecarEphemeralStorageLimit is the limits.ephemeral-storage to set + # for the queue proxy sidecar container. + # If omitted, no value is specified and the system default is used. + queueSidecarEphemeralStorageLimit: "1024Mi" +``` + +## Configuring progress deadlines + +Configuring progress deadline settings allows you to specify the maximum time, either in seconds or minutes, that you will wait for your Deployment to progress before the system reports back that the Deployment has failed progressing for the Knative Revision. + +The default progress deadline is 600 seconds. This value is expressed as a Golang `time.Duration` string representation, and must be rounded to a second precision. + +The Knative Autoscaler component scales the revision to 0, and the Knative service enters a terminal `Failed` state, if the initial scale cannot be achieved within the time limit defined by this setting. + +You may want to configure this setting as a higher value if any of the following issues occur in your Knative deployment: + +- It takes a long time to pull the Service image, due to the size of the image. +- It takes a long time for the Service to become `READY`, due to priming of the initial cache state. +- The cluster is relies on cluster autoscaling to allocate resources for new pods. + +See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#progress-deadline-seconds) for more information. + +The following example shows a snippet of an example Deployment Config Map that sets this value to 10 minutes: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-deployment + namespace: knative-serving + labels: + serving.knative.dev/release: devel + annotations: + knative.dev/example-checksum: "fa67b403" +data: + progressDeadline: "10m" +``` + +## Skipping tag resolution + +You can configure Knative Serving to skip tag resolution for Deployments by modifying the `registriesSkippingTagResolving` ConfigMap setting. + +The following example shows how to disable tag resolution for `registry.example.com`: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: config-deployment + namespace: knative-serving + labels: + serving.knative.dev/release: devel + annotations: + knative.dev/example-checksum: "fa67b403" +data: + # List of repositories for which tag to digest resolving should be skipped + registriesSkippingTagResolving: registry.example.com +``` diff --git a/docs/developer/serving/services/deployment.md b/docs/developer/serving/services/deployment.md deleted file mode 100644 index e08a16ecd..000000000 --- a/docs/developer/serving/services/deployment.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "Modifying the Deployment Config Map" -linkTitle: "Deployment Configuration" -weight: 10 -type: "docs" ---- - -# Modifying the Deployment Config Map - -The `config-deployment` ConfigMap is located in the `knative-serving` namespace. -This ConfigMap, known as the Deployment ConfigMap, contains settings that determine how Kubernetes `Deployment` resources, that back Knative services, are configured. - -## Accessing the Deployment ConfigMap - -To view the current Deployment ConfigMap: - -```bash -kubectl get configmap -n knative-serving config-deployment -oyaml -``` - -## Configuring progress deadlines - -Configuring progress deadline settings allows you to specify the maximum time, either in seconds or minutes, that you will wait for your Deployment to progress before the system reports back that the Deployment has failed progressing for the Knative Revision. -By default, this value is set to 600 seconds. -The value is expressed as a Go `time.Duration` string representation, but must be rounded to a second precision. - -The Knative Autoscaler component scales the revision to 0, and the Knative service enters a terminal `Failed` state, if the initial scale cannot be achieved within the time limit defined by this setting. - -You may want to configure this setting as a higher value if any of the following issues occur in your Knative deployment: - -- It takes a long time to pull the Service image, due to the size of the image. -- It takes a long time for the Service to become `READY`, due to priming of the initial cache state. -- The cluster is relies on cluster autoscaling to allocate resources for new pods. - -See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#progress-deadline-seconds) for more information. - -The following example shows a snippet of an example Deployment Config Map that sets this value to 10 minutes: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-deployment - namespace: knative-serving -data: - ... - progressDeadline: "10m" - ... -``` diff --git a/docs/serving/tag-resolution.md b/docs/serving/tag-resolution.md index b7d09f4da..064abc38c 100644 --- a/docs/serving/tag-resolution.md +++ b/docs/serving/tag-resolution.md @@ -1,10 +1,3 @@ ---- -title: "Enabling tag to digest resolution" -linkTitle: "Tag resolution" -weight: 75 -type: "docs" ---- - # Enabling tag to digest resolution Knative serving resolves image tags to a digest when you create a revision. This @@ -16,6 +9,10 @@ see Unfortunately, this means that the knative serving controller needs to be configured to access your container registry. +!!! tip + + If you are a cluster administrator, you can [modify the `config-deployment` ConfigMap settings](../../admin/serving/deployment) so that tag resolution is skipped for Deployments in the cluster. + ## Custom Certificates If you're using a registry that has a self-signed certificate, you'll need to @@ -72,26 +69,3 @@ spec: - name: HTTPS_PROXY value: https://proxy.example.com ``` - -## Skipping tag resolution - -If this all seems like too much trouble, you can configure serving to skip tag -resolution via the `registriesSkippingTagResolving` configmap field: - -``` -kubectl -n knative-serving edit configmap config-deployment -``` - -E.g., to disable tag resolution for `registry.example.com` (note: This is not a complete configmap, it is a snippet showing registriesSkippingTagResolving): - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: config-deployment - namespace: knative-serving - -data: - # List of repositories for which tag to digest resolving should be skipped - registriesSkippingTagResolving: registry.example.com -``` diff --git a/mkdocs.yml b/mkdocs.yml index bb2b674a5..6b6a1285c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -48,6 +48,9 @@ nav: - Logging: admin/collecting-logs/README.md - Metrics: admin/collecting-metrics/README.md - Uninstalling Knative: admin/install/uninstall.md + # Serving config + - Knative Serving configuration: + - Configure Deployment resources: admin/serving/deployment.md # Developer guide - Developer guide: - Overview: developer/README.md @@ -82,9 +85,8 @@ nav: - Configuring scale bounds: serving/autoscaling/scale-bounds.md - Additional autoscaling configuration for Knative Pod Autoscaler: serving/autoscaling/kpa-specific.md - Autoscale Sample App - Go: serving/autoscaling/autoscale-go/index.md - # Administrator topics + # Admin topics - serving - Administrator Topics: - - Deployment Configuration: serving/services/deployment.md - Kubernetes services: serving/knative-kubernetes-services.md - Accessing request traces: serving/accessing-traces.md - Enabling requests to Knative services when additional authorization policies are enabled: serving/istio-authorization.md @@ -290,6 +292,7 @@ plugins: # Redirects - redirects: redirect_maps: + 'serving/services/deployment.md': 'admin/serving/deployment.md' 'serving/debugging-application-issues.md': 'developer/serving/troubleshooting/debugging-application-issues.md' 'serving/creating-domain-mappings.md': 'developer/serving/services/custom-domains.md' 'eventing/samples/sinkbinding/': 'eventing/sources/sinkbinding/README.md'