View Source KubeProbex (Kube Probex v1.0.1)

Kube Probex is a lightweight and flexible Elixir library designed to help define HTTP probes in Kubernetes for applications built using the Phoenix framework. It leverages Phoenix Plug to integrate seamlessly into your web application, making it easy to ensure that your services remain healthy and responsive in Kubernetes environments.

Features

  • Simple Integration: Add liveness, readiness, and startup probes to your Phoenix app with minimal configuration.
  • Customizable Checks: Define your own liveness, readiness, and startup probes logic to suit your application's needs.
  • Kubernetes-Ready: Built with Kubernetes probe endpoints in mind.
  • Lightweight: Minimal dependencies and easy to use.

Installation

Add kube_probex to your dependencies in mix.exs:

def deps do
[
  {:kube_probex, "~> 1.0.0"}
]
end

Then, fetch the dependencies:

mix deps.get

Usage

Adding the Plugs to Your Phoenix Endpoint or Router

To use kube_probex, add it to your Phoenix endpoint or router as a plug:

Liveness

# lib/my_app_web/endpoint.ex

defmodule MyAppWeb.Endpoint do
use Phoenix.Endpoint, otp_app: :my_app_web

plug KubeProbex.Plug.Liveness, path: ~w(/_health /_healthz)
end

This will expose:

  • A liveness probe endpoint at /_health and /_healthz paths.

Readiness

# lib/my_app_web/endpoint.ex

defmodule MyAppWeb.Endpoint do
use Phoenix.Endpoint, otp_app: :my_app_web

plug KubeProbex.Plug.Readiness, path: ~w(/_ready /_readyz), otp_apps: [:my_app]
end

This will expose:

  • A readiness probe endpoint at /_ready and /_readyz paths.

Note

Check the Available Plugs section in the sidebar for a list of all available plugs.

Customizing Probe Checks

You can define custom probe checks by configuring kube_probex. Add a module implementing one of the check behaviours:

defmodule MyApp.LivenessCheck do
  @behaviour KubeProbex.Check.Liveness

  alias Plug.Conn

  @impl true
  def check(conn, _liveness_plug_opts) do
    if some_condition() do
      conn
      |> Conn.put_resp_content_type("application/json")
      |> Conn.send_resp(200, ~s({"status": "ok"}))
    else
      conn
      |> Conn.put_resp_content_type("application/json")
      |> Conn.send_resp(500, ~s({"status": "error"}))
    end
  end

  defp some_condition do
    # Your custom logic here
    true
  end
end

Then, configure kube_probex to use your custom check in config/config.exs:

config :kube_probex, liveness_check: MyApp.LivenessCheck

Kubernetes Configuration

In your Kubernetes deployment manifest, configure the liveness probe to point to the exposed endpoint:

livenessProbe:
httpGet:
  path: /_health
  port: 4000
initialDelaySeconds: 5
periodSeconds: 10

Note

Check the Behaviours section in the sidebar for a list of all behaviours.