Skip to content

Document period and failure threshold on health checks #245

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document period and failure threshold on health checks #245

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions applications/configuration-as-code/services/web-service.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,15 +126,23 @@ 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:
enabled: true
httpPath: /healthz
timeoutSeconds: 1
initialDelaySeconds: 15
periodSeconds: 10
failureThreshold: 3
```

<Info>
`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.
</Info>

<Warning>
Cannot be used together with `livenessCheck`, `readinessCheck`, or `startupCheck`. Use either the combined `healthCheck` or the individual checks.
</Warning>
Expand Down Expand Up @@ -163,6 +171,8 @@ livenessCheck:
httpPath: /livez
timeoutSeconds: 1
initialDelaySeconds: 15
periodSeconds: 10
failureThreshold: 3
```

### `readinessCheck`
Expand All @@ -179,6 +189,8 @@ readinessCheck:
httpPath: /readyz
timeoutSeconds: 1
initialDelaySeconds: 15
periodSeconds: 5
failureThreshold: 3
```

### `startupCheck`
Expand All @@ -195,8 +207,18 @@ startupCheck:
httpPath: /startupz
timeoutSeconds: 1
initialDelaySeconds: 15
periodSeconds: 10
failureThreshold: 30
```

<Tip>
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.
</Tip>

<Note>
`periodSeconds` and `failureThreshold` are supported on each of `livenessCheck`, `readinessCheck`, and `startupCheck` and follow the same minimum-of-1 validation as the combined `healthCheck`.
</Note>

---

## `pathRouting`
Expand Down
18 changes: 18 additions & 0 deletions applications/configuration-as-code/services/worker-service.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,15 +66,23 @@ 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:
enabled: true
command: ./healthcheck.sh
timeoutSeconds: 5
initialDelaySeconds: 15
periodSeconds: 10
failureThreshold: 3
```

<Info>
`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.
</Info>

<Warning>
Cannot be used together with `livenessCheck`, `readinessCheck`, or `startupCheck`. Use either the combined `healthCheck` or the individual checks.
</Warning>
Expand Down Expand Up @@ -103,6 +111,8 @@ livenessCheck:
command: ./livez.sh
timeoutSeconds: 5
initialDelaySeconds: 15
periodSeconds: 10
failureThreshold: 3
```

### `readinessCheck`
Expand All @@ -119,6 +129,8 @@ readinessCheck:
command: ./readyz.sh
timeoutSeconds: 5
initialDelaySeconds: 5
periodSeconds: 5
failureThreshold: 3
```

### `startupCheck`
Expand All @@ -135,8 +147,14 @@ startupCheck:
command: ./startupz.sh
timeoutSeconds: 10
initialDelaySeconds: 0
periodSeconds: 10
failureThreshold: 30
```

<Note>
`periodSeconds` and `failureThreshold` are supported on each of `livenessCheck`, `readinessCheck`, and `startupCheck` and follow the same minimum-of-1 validation as the combined `healthCheck`.
</Note>

---

## `connections`
Expand Down
6 changes: 6 additions & 0 deletions applications/deploy/configuring-application-services.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down