Merge pull request #84730 from ochromy/SRVKS-1257

[SRVKS-1257] Add startup probes documentation

Author: skrthomas

_topic_maps/_topic_map.yml

@@ -134,6 +134,8 @@ Topics:
     File: pvcs-for-serving
   - Name: Init containers
     File: init-containers
+  - Name: Startup probes
+    File: startup-probes-for-serving
   - Name: Resolving image tags to digests
     File: resolving-image-tags-to-digests
   - Name: Configuring Kourier

knative-serving/config-applications/startup-probes-for-serving.adoc

@@ -0,0 +1,21 @@
+:_content-type: ASSEMBLY
+include::_attributes/common-attributes.adoc[]
+[id="startup-probes-for-serving"]
+= Startup probes
+:context: startup-probes-for-serving
+
+toc::[]
+
+Startup probes verify whether a service has started successfully, helping to reduce cold start times for containers with slow startup processes.
+Startup probes run only during the container's initialization phase and do not execute periodically. If a startup probe fails, the container adheres to the defined `restartPolicy`.
+
+//TODO: architecture diagram
+
+//Progress Deadline
+include::modules/serverless-progress-deadline-serving.adoc[leveloffset=+1]
+
+// Configuring Startup Probes
+include::modules/serverless-configuring-startup-probing-serving.adoc[leveloffset=+1]
+
+//Configuring Progress Deadline
+include::modules/serverless-configuring-progress-deadline-serving.adoc[leveloffset=+1]

modules/serverless-configuring-progress-deadline-serving.adoc

@@ -0,0 +1,40 @@
+// Module included in the following assemblies:
+//
+// * serverless/knative-serving/config-applications/startup-probes-for-serving.adoc
+
+:_content-type: PROCEDURE
+[id="serverless-configuring-progress-deadline-serving_{context}"]
+= Configuring the progress deadline
+
+You can configure progress deadline settings to specify the maximum time allowed for your deployment to progress before the system reports a failure for the Knative Revision. This time limit can be specified in seconds or minutes.
+
+To configure the progress deadline effectively, consider the following parameters:
+
+ * `initialDelaySeconds`
+ * `failureThreshold` 
+ * `periodSeconds`
+ * `timeoutSeconds`
+
+If the initial scale is not achieved within the specified time limit, the Knative Autoscaler component scales the revision to `0`, and the Knative service enters a terminal `Failed` state.
+
+By default, the progress deadline is set to 600 seconds. This value is specified as a Golang `time.Duration` string and must be rounded to the nearest second.
+
+.Procedure
+
+* To configure the progress deadline setting, use an annotation in your deployment configuration.
++
+.Example of progress deadline set to 60 seconds
+[source,yaml]
+----
+apiVersion: serving.knative.dev/v1
+kind: Service
+...
+spec:
+  template:
+    metadata:
+       annotations:
+            serving.knative.dev/progress-deadline: "60s"
+    spec:
+        containers:
+            - image: ghcr.io/knative/helloworld-go:latest
+----

modules/serverless-configuring-startup-probing-serving.adoc

@@ -0,0 +1,43 @@
+// Module included in the following assemblies:
+//
+// * serverless/knative-serving/config-applications/startup-probes-for-serving.adoc
+
+:_content-type: PROCEDURE
+[id="serverless-configuring-startup-probing-serving_{context}"]
+= Configuring startup probing
+
+For {ServerlessProductName} Serving, startup probes are not defined by default. You can define startup probes for your containers in your deployment configuration. 
+
+.Procedure
+
+* Define startup probes for your service by modifying your deployment configuration. The following example shows a configuration with two containers:
++
+.Example of defined starup probes 
+[source,yaml]
+----
+apiVersion: serving.knative.dev/v1
+kind: Service
+# ...
+spec:
+  template:
+    spec:
+       containers:
+        - name: first-container
+          image: <image>
+          ports:
+            - containerPort: 8080
+          # ...
+          startupProbe: <1>
+          httpGet:
+            port: 8080
+            path: "/"
+        - name: second-container
+          image: <image>
+          # ...
+          startupProbe: <2>
+          httpGet:
+            port: 8081
+            path: "/"
+----
+<1> Startup probe of the `first-container`.
+<2> Startup probe of the `second-container`.

modules/serverless-progress-deadline-serving.adoc

@@ -0,0 +1,15 @@
+// Module included in the following assemblies:
+//
+// * serverless/knative-serving/config-applications/startup-probes-for-serving.adoc
+
+:_content-type: CONCEPT
+[id="serverless-progress-deadline-serving_{context}"]
+= Progress deadline
+
+By default, services have a progress deadline that defines the time limit for a service to complete its initial startup. When using startup probes, ensure that the progress deadline is set to exceed the maximum time required by the startup probes. If the progress deadline is set too low, the startup probes might not finish before the deadline is reached, which can prevent the service from starting.
+
+Consider increasing the progress deadline if you encounter any of these conditions in your deployment:
+
+* The service image takes a long time to pull due to its size.
+* The service takes a long time to become `READY` because of initial cache priming.
+* The cluster relies on autoscaling to allocate resources for new pods.