From f07a86a9be5c43db4f27b6f1c16deb0a956b90d9 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 11 May 2026 22:05:40 +0000
Subject: [PATCH] Document periodSeconds and failureThreshold on health checks
Generated-By: mintlify-agent
---
.../services/web-service.mdx | 22 +++++++++++++++++++
.../services/worker-service.mdx | 18 +++++++++++++++
.../configuring-application-services.mdx | 6 +++++
3 files changed, 46 insertions(+)
diff --git a/applications/configuration-as-code/services/web-service.mdx b/applications/configuration-as-code/services/web-service.mdx
index 50bad48..f6e724c 100644
--- a/applications/configuration-as-code/services/web-service.mdx
+++ b/applications/configuration-as-code/services/web-service.mdx
@@ -126,6 +126,8 @@ Configure a combined health check that applies to liveness, readiness, and start
| `httpPath` | string | HTTP endpoint to check |
| `timeoutSeconds` | integer | Request timeout (min: 1) |
| `initialDelaySeconds` | integer | Initial delay before checking (min: 0) |
+| `periodSeconds` | integer | How often to perform the health check (min: 1) |
+| `failureThreshold` | integer | Consecutive failures before the container is considered unhealthy (min: 1) |
```yaml
healthCheck:
@@ -133,8 +135,14 @@ healthCheck:
httpPath: /healthz
timeoutSeconds: 1
initialDelaySeconds: 15
+ periodSeconds: 10
+ failureThreshold: 3
```
+
+`periodSeconds` and `failureThreshold` are optional. When omitted, Kubernetes defaults are used (`periodSeconds: 10`, `failureThreshold: 3`). Increase `failureThreshold` or `periodSeconds` for applications that may have transient slowness, and decrease them for faster failure detection.
+
+
Cannot be used together with `livenessCheck`, `readinessCheck`, or `startupCheck`. Use either the combined `healthCheck` or the individual checks.
@@ -163,6 +171,8 @@ livenessCheck:
httpPath: /livez
timeoutSeconds: 1
initialDelaySeconds: 15
+ periodSeconds: 10
+ failureThreshold: 3
```
### `readinessCheck`
@@ -179,6 +189,8 @@ readinessCheck:
httpPath: /readyz
timeoutSeconds: 1
initialDelaySeconds: 15
+ periodSeconds: 5
+ failureThreshold: 3
```
### `startupCheck`
@@ -195,8 +207,18 @@ startupCheck:
httpPath: /startupz
timeoutSeconds: 1
initialDelaySeconds: 15
+ periodSeconds: 10
+ failureThreshold: 30
```
+
+For slow-starting containers, set `failureThreshold` on `startupCheck` high enough that `periodSeconds * failureThreshold` covers your worst-case startup time. Once the startup probe succeeds, the liveness and readiness probes take over.
+
+
+
+`periodSeconds` and `failureThreshold` are supported on each of `livenessCheck`, `readinessCheck`, and `startupCheck` and follow the same minimum-of-1 validation as the combined `healthCheck`.
+
+
---
## `pathRouting`
diff --git a/applications/configuration-as-code/services/worker-service.mdx b/applications/configuration-as-code/services/worker-service.mdx
index a2ecdd4..264f099 100644
--- a/applications/configuration-as-code/services/worker-service.mdx
+++ b/applications/configuration-as-code/services/worker-service.mdx
@@ -66,6 +66,8 @@ Configure a combined health check that applies to liveness, readiness, and start
| `command` | string | Command to run for health check |
| `timeoutSeconds` | integer | Command timeout (min: 1) |
| `initialDelaySeconds` | integer | Initial delay before checking (min: 0) |
+| `periodSeconds` | integer | How often to perform the health check (min: 1) |
+| `failureThreshold` | integer | Consecutive failures before the container is considered unhealthy (min: 1) |
```yaml
healthCheck:
@@ -73,8 +75,14 @@ healthCheck:
command: ./healthcheck.sh
timeoutSeconds: 5
initialDelaySeconds: 15
+ periodSeconds: 10
+ failureThreshold: 3
```
+
+`periodSeconds` and `failureThreshold` are optional. When omitted, Kubernetes defaults are used (`periodSeconds: 10`, `failureThreshold: 3`). Tune these for long-running jobs that may need more time between checks or a higher tolerance for transient failures.
+
+
Cannot be used together with `livenessCheck`, `readinessCheck`, or `startupCheck`. Use either the combined `healthCheck` or the individual checks.
@@ -103,6 +111,8 @@ livenessCheck:
command: ./livez.sh
timeoutSeconds: 5
initialDelaySeconds: 15
+ periodSeconds: 10
+ failureThreshold: 3
```
### `readinessCheck`
@@ -119,6 +129,8 @@ readinessCheck:
command: ./readyz.sh
timeoutSeconds: 5
initialDelaySeconds: 5
+ periodSeconds: 5
+ failureThreshold: 3
```
### `startupCheck`
@@ -135,8 +147,14 @@ startupCheck:
command: ./startupz.sh
timeoutSeconds: 10
initialDelaySeconds: 0
+ periodSeconds: 10
+ failureThreshold: 30
```
+
+`periodSeconds` and `failureThreshold` are supported on each of `livenessCheck`, `readinessCheck`, and `startupCheck` and follow the same minimum-of-1 validation as the combined `healthCheck`.
+
+
---
## `connections`
diff --git a/applications/deploy/configuring-application-services.mdx b/applications/deploy/configuring-application-services.mdx
index a00695e..39e42cb 100644
--- a/applications/deploy/configuring-application-services.mdx
+++ b/applications/deploy/configuring-application-services.mdx
@@ -148,6 +148,12 @@ The **initial delay** gives your application time to start up before health chec
The **timeout** determines how long Porter waits for a response before considering the check failed.
+The **period** controls how often the health check runs, in seconds. Lower values catch failures faster at the cost of additional load on your application.
+
+The **failure threshold** is the number of consecutive failed checks before Porter considers the container unhealthy and restarts it. Increase this for applications that may experience transient slowness, or decrease it for faster failure detection. Both fields must be at least `1`; leave them blank to use the Kubernetes defaults (`period: 10`, `failure threshold: 3`).
+
+When using **Advanced** health checks, `period` and `failure threshold` can be configured independently for each of the liveness, readiness, and startup probes.
+
For best practices on combining health checks with graceful shutdown, see [Zero-Downtime Deployments](/applications/configure/zero-downtime-deployments).
### Metrics scraping