https://github.com/joeapearson/elixir-k8s-probe
Provides configurable HTTP liveness and readiness endpoints for Elixir applications, intended to be used to support Kubernetes probes.
https://github.com/joeapearson/elixir-k8s-probe
elixir kubernetes liveness probe readiness
Last synced: 11 months ago
JSON representation
Provides configurable HTTP liveness and readiness endpoints for Elixir applications, intended to be used to support Kubernetes probes.
- Host: GitHub
- URL: https://github.com/joeapearson/elixir-k8s-probe
- Owner: joeapearson
- License: mit
- Created: 2020-09-26T04:48:48.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2021-06-28T01:18:03.000Z (almost 5 years ago)
- Last Synced: 2025-06-29T04:16:43.647Z (12 months ago)
- Topics: elixir, kubernetes, liveness, probe, readiness
- Language: Elixir
- Homepage:
- Size: 25.4 KB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# K8sProbe
Provides configurable HTTP liveness and readiness endpoints, intended to be used to support
[Kubernetes probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/).
`K8sProbe` ships with a built-in `Cowboy` HTTP server making this module easy to integrate into
any project.
## Usage
### Installation
First, add `:k8s_probe` to your `mix.exs` dependencies like so:
```elixir
defp deps do
[
# … your other various dependencies
{:k8s_probe, "0.3.0"}
]
end
```
If necessary run `mix deps.get` and `mix deps.compile` at this point to fetch and compile
`K8sProbe`.
Next, add `K8sProbe` to your supervision tree (perhaps in your `application.ex` file). It would
look something like this:
```elixir
defmodule MyApp.Application do
use Application
def start(_type, _args) do
children = [
K8sProbe
]
opts = [strategy: :one_for_one, name: MyApp.Supervisor]
Supervisor.start_link(children, opts)
end
end
```
Now you can try it out by launching your application and making a request to the probe endpoints
as follows:
```sh
# Start your app in iex
$ iex -S mix
# In another terminal
$ curl localhost:9991/readiness
OK
$ curl localhost:9991/liveness
OK
```
Congratulations, you have a default probe up and running!
### Customising the probe
This module ships with a completely minimal default probe that does nothing other than respond
with a `200 OK`, regardless of the state of your application.
This might be fine for simple applications, but for a more detailed implementation you need to
provide your own probe implementing the `K8sProbe.Probe` behaviour. Here's an example:
```elixir
defmodule MyApp.MyProbe do
@behaviour K8sProbe.Probe
def readiness, do: :ok
def liveness, do: :ok
end
```
Each of the probe functions must return either `:ok` or `:error`. How you implement your probe
really depends on your application.
Having written your probe, you can configure K8sProbe to use it by passing it in the configuration.
Here's what your `application.ex` file might look like:
```elixir
defmodule MyApp.Application do
use Application
def start(_type, _args) do
children = [
{K8sProbe, probe_module: MyApp.MyProbe}
]
opts = [strategy: :one_for_one, name: MyApp.Supervisor]
Supervisor.start_link(children, opts)
end
end
```
## Configuration
Generally it's recommended to just use the default configuration; easier isn't it! But if you
must then read on...
### Port
By default K8sProbe listens on port 9991. You may override it by passing it as config option.
## Configuring probes in Kubernetes
Here's an example Kubernetes deployment in YAML format that calls the probes as implemented by
default:
```yaml
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-service
spec:
replicas: 1
selector:
matchLabels:
app.kubernetes.io/name: my-service
template:
spec:
containers:
name: my-service
image: my-service
ports:
- containerPort: 9991
name: liveness-port
protocol: TCP
readinessProbe:
httpGet:
path: /readiness
port: liveness-port
livenessProbe:
httpGet:
path: /liveness
port: liveness-port
startupProbe:
httpGet:
path: /readiness
port: liveness-port
```
You'll need to modify this configuration before it will work of course, replacing the image with
your own.
Configuring Kubernetes to make use of the probes provided by this module is a topic unto itself.
See
[here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)
for more information.