76 lines
2.4 KiB
Markdown
76 lines
2.4 KiB
Markdown
|
# Service Model and Healthchecks
|
||
|
|
|
||
|
|
This document defines the normalized service model for the homelab.
|
||
|
|
|
||
|
|
## Service Layout
|
||
|
|
|
||
|
|
Each service must reside in its own directory under `services/`:
|
||
|
|
|
||
|
|
```text
|
||
|
|
services/<service>/
|
||
|
|
├── docker-compose.yml # Docker Compose definition
|
||
|
|
├── service.yaml # Service metadata and orchestration contract
|
||
|
|
├── README.md # Service documentation
|
||
|
|
├── env.example # Template for required environment variables
|
||
|
|
└── healthcheck.sh # Standardized healthcheck script
|
||
|
|
```
|
||
|
|
|
||
|
|
## Service Metadata (`service.yaml`)
|
||
|
|
|
||
|
|
The `service.yaml` file provides a machine-readable contract for deployment and orchestration.
|
||
|
|
|
||
|
|
### Schema
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
service:
|
||
|
|
name: <string> # Canonical service name (kebab-case)
|
||
|
|
owner_node: <string> # Preferred host node
|
||
|
|
exposure: <class> # public, private, or local-only
|
||
|
|
dependencies: [<service>] # List of required services
|
||
|
|
ports:
|
||
|
|
- container: <int>
|
||
|
|
host: <int>
|
||
|
|
protocol: <tcp|udp>
|
||
|
|
healthcheck:
|
||
|
|
type: <string> # local-only, container, http, mqtt
|
||
|
|
endpoint: <string> # URL or topic if applicable
|
||
|
|
interval: <duration>
|
||
|
|
timeout: <duration>
|
||
|
|
retries: <int>
|
||
|
|
restart_policy: <string> # unless-stopped, always, etc.
|
||
|
|
persistence:
|
||
|
|
paths:
|
||
|
|
- /opt/homelab/data/<service>/...
|
||
|
|
runtime:
|
||
|
|
directories: [<string>] # Required host directories to be created
|
||
|
|
env_vars: [<string>] # List of required environment variables (keys only)
|
||
|
|
```
|
||
|
|
|
||
|
|
## Healthcheck Semantics
|
||
|
|
|
||
|
|
The `healthcheck.sh` script should return `0` for healthy and `1` for unhealthy. It should support different modes based on `service.yaml` definitions.
|
||
|
|
|
||
|
|
### 1. Local-only
|
||
|
|
Checks if the container is running and the process is alive within the host.
|
||
|
|
|
||
|
|
### 2. Container-level
|
||
|
|
Uses `docker inspect` or `docker exec` to check internal container health.
|
||
|
|
|
||
|
|
### 3. HTTP
|
||
|
|
Performs a `curl` against a specific endpoint (e.g., `/health` or `/`).
|
||
|
|
|
||
|
|
### 4. MQTT
|
||
|
|
Verifies that a specific topic is being updated or responds to a ping.
|
||
|
|
|
||
|
|
### 5. Dependency-aware
|
||
|
|
The healthcheck script may optionally check if its dependencies are healthy before reporting its own status.
|
||
|
|
|
||
|
|
## Runtime Authority
|
||
|
|
|
||
|
|
`/opt/homelab/config/<service>` is the source of truth for:
|
||
|
|
- Secrets (not in Git)
|
||
|
|
- Host-local overrides
|
||
|
|
- Mutable configuration
|
||
|
|
|
||
|
|
Services should mount files from this directory as needed.
|