Skip to content

Commit b3a958b

Browse files
marle3003marle3003
committed
doc: add health check documentation
1 parent 3450d00 commit b3a958b

3 files changed

Lines changed: 229 additions & 0 deletions

File tree

‎docs/config.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,11 @@
182182
"path": "/docs/configuration/reference"
183183
}
184184
]
185+
},
186+
{
187+
"label": "Health Check",
188+
"source": "configuration/healthcheck.md",
189+
"path": "/docs/configuration/health-check"
185190
}
186191
]
187192
},

‎docs/configuration/healthcheck.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
---
2+
title: Health Check Configuration
3+
description: Configure Mokapi's health endpoint for uptime monitoring, orchestration systems, and Kubernetes probes.
4+
subtitle: Configure Mokapi's health endpoint for uptime monitoring, orchestration systems, and Kubernetes probes.
5+
---
6+
7+
# Health Check Configuration
8+
9+
## Overview
10+
11+
Mokapi provides a simple health endpoint to monitor service availability. This endpoint can be used for:
12+
13+
- **Uptime monitoring:** Check if Mokapi is responding to requests
14+
- **Load balancer health checks:** Ensure traffic is only routed to healthy instances
15+
- **Kubernetes probes:** Liveness and readiness probes for pod management
16+
- **CI/CD validation:** Verify Mokapi started successfully before running tests
17+
18+
By default, the health check listens on `http://localhost:8080/health` but can be fully customized.
19+
20+
``` box=info title"Simple Health Check"
21+
The health endpoint is minimal and does not perform checks of external dependencies. It simply indicates that Mokapi is up and listening. A 200 OK response means Mokapi is ready to accept requests.
22+
```
23+
24+
## Configuration
25+
26+
Configure the health endpoint using YAML configuration or CLI flags. The health endpoint is controlled by the health section:
27+
28+
```yaml
29+
health:
30+
enabled: true
31+
path: /health
32+
port: 8080
33+
log: false
34+
```
35+
36+
### Configuration Fields
37+
38+
<div class="table-responsive-sm">
39+
<table>
40+
<thead>
41+
<tr>
42+
<th class="col-2">Field</th>
43+
<th class="col-2">Type</th>
44+
<th class="col-2">Default</th>
45+
<th class="col">Description</th>
46+
</tr>
47+
</thead>
48+
<tbody>
49+
<tr>
50+
<td>enabled</td>
51+
<td>bool</td>
52+
<td>true</td>
53+
<td>Enables or disables the health check endpoint. When `false`, Mokapi does not expose any health endpoint.</td>
54+
</tr>
55+
<tr>
56+
<td>path</td>
57+
<td>string</td>
58+
<td>/health</td>
59+
<td>The HTTP path for the health endpoint. Must start with /.</td>
60+
</tr>
61+
<tr>
62+
<td>port</td>
63+
<td>int</td>
64+
<td>8080</td>
65+
<td>The port on which the health endpoint is exposed. If it matches the API/dashboard port, the health endpoint is served by the same HTTP server.</td>
66+
</tr>
67+
<tr>
68+
<td>log</td>
69+
<td>bool</td>
70+
<td>false</td>
71+
<td>If `true`, Mokapi logs all requests to the health endpoint using structured JSON logs. Useful for debugging but can generate high log volume.</td>
72+
</tr>
73+
</tbody>
74+
</table>
75+
</div>
76+
77+
### Example Configuration
78+
79+
```yaml
80+
health:
81+
enabled: true
82+
path: /healthz # Custom path
83+
port: 8081 # Dedicated port
84+
log: true # Enable logging for debugging
85+
```
86+
87+
### CLI Flags
88+
89+
The health endpoint can also be configured using command-line flags:
90+
91+
<div class="table-responsive-sm">
92+
<table>
93+
<thead>
94+
<tr>
95+
<th class="col-2">Flag</th>
96+
<th class="col-4">Description</th>
97+
<th class="col-4">Example</th>
98+
</tr>
99+
</thead>
100+
<tbody>
101+
<tr>
102+
<td>--health-enabled</td>
103+
<td>Enable or disable the health endpoint</td>
104+
<td><code>mokapi --health-enabled=true</code></td>
105+
</tr>
106+
<tr>
107+
<td>--health-path</td>
108+
<td>Path for the health endpoint</td>
109+
<td><code>mokapi --health-path=/healthz</code></td>
110+
</tr>
111+
<tr>
112+
<td>--health-port</td>
113+
<td>Port for the health endpoint</td>
114+
<td><code>mokapi --health-port=8081</code></td>
115+
</tr>
116+
<tr>
117+
<td>--health-log</td>
118+
<td>Log all health requests</td>
119+
<td><code>mokapi --health-log</code></td>
120+
</tr>
121+
</tbody>
122+
</table>
123+
</div>
124+
125+
### Example Command
126+
127+
```
128+
mokapi /api/spec.yaml \
129+
--health-path=/healthz \
130+
--health-port=8081 \
131+
--health-log
132+
```
133+
134+
## Health Endpoint Response
135+
136+
When Mokapi is healthy and responding, the endpoint returns:
137+
138+
```http
139+
GET /health HTTP/1.1
140+
Host: localhost:8080
141+
142+
HTTP/1.1 200 OK
143+
Content-Type: application/json
144+
145+
{"status":"healthy"}
146+
```
147+
148+
- **Status Code:** 200 OK indicates the service is healthy and ready to accept requests
149+
- **Content Type:** application/json
150+
- **Body:** JSON object with status: "healthy"
151+
152+
``` box=warning title="Limited Health Check"
153+
The health endpoint only validates that Mokapi's HTTP server is running and can process requests.
154+
```
155+
156+
## Kubernetes Integration
157+
158+
Use Mokapi's health endpoint with Kubernetes liveness and readiness probes to ensure proper orchestration:
159+
160+
```yaml
161+
apiVersion: apps/v1
162+
kind: Deployment
163+
metadata:
164+
name: mokapi
165+
spec:
166+
replicas: 1
167+
selector:
168+
matchLabels:
169+
app: mokapi
170+
template:
171+
metadata:
172+
labels:
173+
app: mokapi
174+
spec:
175+
containers:
176+
- name: mokapi
177+
image: mokapi:latest
178+
ports:
179+
- containerPort: 8080
180+
livenessProbe:
181+
httpGet:
182+
path: /health
183+
port: 8080
184+
initialDelaySeconds: 5
185+
periodSeconds: 10
186+
timeoutSeconds: 2
187+
failureThreshold: 3
188+
readinessProbe:
189+
httpGet:
190+
path: /health
191+
port: 8080
192+
initialDelaySeconds: 3
193+
periodSeconds: 5
194+
timeoutSeconds: 2
195+
successThreshold: 1
196+
```
197+
198+
### Understanding the Probes
199+
200+
**Liveness Probe:** Kubernetes uses this to determine if the container is alive. If the liveness probe fails, Kubernetes restarts the container.
201+
202+
**Readiness Probe:** Kubernetes uses this to determine if the container is ready to accept traffic. If the readiness probe fails, Kubernetes removes the pod from service endpoints.
203+
204+
``` box=info title="Single Endpoint for Both Probes"
205+
Mokapi provides only one health endpoint (/health). Both livenessProbe and readinessProbe can point to
206+
the same endpoint. The probes differ in their configuration (timing, thresholds), not the endpoint they check.
207+
```
208+
209+
### Kubernetes Configuration Notes
210+
211+
- **Port conflicts:** Ensure the health port does not conflict with mocked APIs or dashboard ports in the same container
212+
- **Timing:** Adjust `initialDelaySeconds` based on Mokapi's startup time with your configuration
213+
- **Logging:** If `log`: true is enabled, health requests will appear in logs
214+
- **Failure thresholds:** Set appropriate `failureThreshold` values to avoid premature restarts
215+
216+
## Best Practices
217+
218+
- **Use a dedicated port (optional):**
219+
If your mocked APIs or dashboard run on port 8080, consider setting `health.port` to a different port (e.g., 8081) to avoid conflicts and simplify network routing.
220+
- **Enable logging only when debugging:**
221+
High-frequency probes can generate significant log volume. Use `log: true` only when troubleshooting probe failures or validating probe configuration.

‎webui/src/views/DocsView.vue‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -314,6 +314,9 @@ table {
314314
margin-bottom: 20px;
315315
font-size: 0.9rem;
316316
}
317+
.content table tbody td {
318+
padding: 4px 0 3px 12px;
319+
}
317320
table.selectable td {
318321
cursor: pointer;
319322
}

0 commit comments

Comments
 (0)