salus 0.1.3

Single-shot container health check probe runner for Docker and Kubernetes workloads
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

<p align="center">
  <img src="assets/salus-logo.svg" alt="salus logo" width="720">
</p>

# salus

`salus` is a Rust health check tool for Docker and Kubernetes workloads. It provides a single-shot probe execution model that fits container health checks cleanly.

Supported probe types:

- `http` / `https`
- `tcp`
- `grpc` (standard `grpc.health.v1.Health/Check` only)
- `exec`
- `file`

## Design Goals

- Single execution with stable exit codes for Docker `HEALTHCHECK` and Kubernetes `exec` probes
- Works in minimal container images without requiring a shell
- Supports strict TLS, custom CAs, client certificates, and SNI / hostname overrides
- Failure output is optimized for troubleshooting, while successful probes stay quiet by default

## Architecture

`salus` is easiest to understand as a runtime adapter between the container platform and the probe target inside the workload.

```mermaid
flowchart LR
    subgraph Platform["Container platform"]
        Docker["Docker HEALTHCHECK"]
        K8s["Kubernetes exec probe"]
    end

    subgraph Container["Application container"]
        Salus["salus"]
        HttpTarget["HTTP / HTTPS endpoint"]
        TcpTarget["TCP listener / Unix socket"]
        GrpcTarget["gRPC health service"]
        FileTarget["State / readiness file"]
        ExecTarget["Local validation command"]
    end

    Docker --> Salus
    K8s --> Salus

    Salus --> HttpTarget
    Salus --> TcpTarget
    Salus --> GrpcTarget
    Salus --> FileTarget
    Salus --> ExecTarget

    Salus --> Result["Exit code 0 / 1 / 3 / 4"]
    Result --> Docker
    Result --> K8s
```

## Exit Codes

- `0`: healthy
- `1`: probe failure
- `3`: invalid arguments or configuration
- `4`: internal error

## Examples

HTTP:

```bash
salus http --url http://127.0.0.1:8080/healthz
salus http --url http://127.0.0.1:8080/healthz --request-header x-api-key:secret
salus http --url https://127.0.0.1:8443/ready --ca-file /etc/ssl/health-ca.pem --server-name localhost
salus http --url https://127.0.0.1:8443/ready --ca-file /etc/ssl/health-ca.pem --server-name localhost --response-header-contains x-ready:ok
```

TCP:

```bash
salus tcp --address 127.0.0.1:5432
```

gRPC health:

```bash
salus grpc --address 127.0.0.1:50051
salus grpc --address 127.0.0.1:50051 --tls --ca-file /etc/ssl/grpc-ca.pem --server-name localhost
```

Exec:

```bash
salus exec --stdout-contains ok -- /app/bin/check-ready
```

File:

```bash
salus file --path /tmp/ready --non-empty --contains ready
```

## Docker

The production Dockerfile builds a static musl binary and runs it from `scratch`.
Published images are pushed to `ghcr.io/lvillis/salus:<tag>` and stable tags also update `ghcr.io/lvillis/salus:latest`.

```dockerfile
HEALTHCHECK --interval=10s --timeout=3s --retries=3 CMD ["/bin/salus", "http", "--url", "http://127.0.0.1:8080/healthz"]
```

Copy `salus` into an application image:

```dockerfile
FROM ghcr.io/lvillis/salus:latest AS salus

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=salus /bin/salus /bin/salus
COPY ./my-app /bin/my-app

HEALTHCHECK --interval=10s --timeout=3s --retries=3 CMD ["/bin/salus", "http", "--url", "http://127.0.0.1:8080/healthz", "--body-contains", "ok"]

ENTRYPOINT ["/bin/my-app"]
```

## Kubernetes

Prefer native `httpGet`, `tcpSocket`, and `grpc` probes for simple cases. Use `exec` with `salus` when you need stricter TLS controls, file checks, process-based checks, or richer assertions.

```yaml
livenessProbe:
  exec:
    command:
      - /bin/salus
      - grpc
      - --address
      - 127.0.0.1:50051
      - --tls
      - --ca-file
      - /etc/tls/ca.pem
      - --server-name
      - localhost
```