{"id":14975811,"url":"https://github.com/joeapearson/elixir-k8s-probe","last_synced_at":"2025-07-22T14:32:55.279Z","repository":{"id":57511237,"uuid":"298739247","full_name":"joeapearson/elixir-k8s-probe","owner":"joeapearson","description":"Provides configurable HTTP liveness and readiness endpoints for Elixir applications, intended to be used to support Kubernetes probes.","archived":false,"fork":false,"pushed_at":"2021-06-28T01:18:03.000Z","size":26,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-29T04:16:43.647Z","etag":null,"topics":["elixir","kubernetes","liveness","probe","readiness"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joeapearson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-26T04:48:48.000Z","updated_at":"2024-02-19T10:48:00.000Z","dependencies_parsed_at":"2022-09-26T16:31:09.311Z","dependency_job_id":null,"html_url":"https://github.com/joeapearson/elixir-k8s-probe","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/joeapearson/elixir-k8s-probe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeapearson%2Felixir-k8s-probe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeapearson%2Felixir-k8s-probe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeapearson%2Felixir-k8s-probe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeapearson%2Felixir-k8s-probe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joeapearson","download_url":"https://codeload.github.com/joeapearson/elixir-k8s-probe/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeapearson%2Felixir-k8s-probe/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266510437,"owners_count":23940655,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","kubernetes","liveness","probe","readiness"],"created_at":"2024-09-24T13:52:41.249Z","updated_at":"2025-07-22T14:32:55.245Z","avatar_url":"https://github.com/joeapearson.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# K8sProbe\n\nProvides configurable HTTP liveness and readiness endpoints, intended to be used to support\n[Kubernetes probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/).\n\n`K8sProbe` ships with a built-in `Cowboy` HTTP server making this module easy to integrate into\nany project.\n\n## Usage\n\n### Installation\n\nFirst, add `:k8s_probe` to your `mix.exs` dependencies like so:\n\n```elixir\ndefp deps do\n  [\n    # … your other various dependencies\n    {:k8s_probe, \"0.3.0\"}\n  ]\nend\n```\n\nIf necessary run `mix deps.get` and `mix deps.compile` at this point to fetch and compile\n`K8sProbe`.\n\nNext, add `K8sProbe` to your supervision tree (perhaps in your `application.ex` file).  It would\nlook something like this:\n\n```elixir\ndefmodule MyApp.Application do\n  use Application\n\n  def start(_type, _args) do\n    children = [\n      K8sProbe\n    ]\n\n    opts = [strategy: :one_for_one, name: MyApp.Supervisor]\n    Supervisor.start_link(children, opts)\n  end\nend\n```\n\nNow you can try it out by launching your application and making a request to the probe endpoints\nas follows:\n\n```sh\n# Start your app in iex\n$ iex -S mix\n\n# In another terminal\n$ curl localhost:9991/readiness\nOK\n$ curl localhost:9991/liveness\nOK\n```\n\nCongratulations, you have a default probe up and running!\n\n### Customising the probe\n\nThis module ships with a completely minimal default probe that does nothing other than respond\nwith a `200 OK`, regardless of the state of your application.\n\nThis might be fine for simple applications, but for a more detailed implementation you need to\nprovide your own probe implementing the `K8sProbe.Probe` behaviour.  Here's an example:\n\n```elixir\ndefmodule MyApp.MyProbe do\n  @behaviour K8sProbe.Probe\n  def readiness, do: :ok\n  def liveness, do: :ok\nend\n```\n\nEach of the probe functions must return either `:ok` or `:error`.  How you implement your probe\nreally depends on your application.\n\nHaving written your probe, you can configure K8sProbe to use it by passing it in the configuration.\nHere's what your `application.ex` file might look like:\n\n```elixir\ndefmodule MyApp.Application do\n  use Application\n\n  def start(_type, _args) do\n    children = [\n      {K8sProbe, probe_module: MyApp.MyProbe}\n    ]\n\n    opts = [strategy: :one_for_one, name: MyApp.Supervisor]\n    Supervisor.start_link(children, opts)\n  end\nend\n```\n\n## Configuration\n\nGenerally it's recommended to just use the default configuration; easier isn't it!  But if you\nmust then read on...\n\n### Port\n\nBy default K8sProbe listens on port 9991.  You may override it by passing it as config option.\n\n## Configuring probes in Kubernetes\n\nHere's an example Kubernetes deployment in YAML format that calls the probes as implemented by\ndefault:\n\n```yaml\n---\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: my-service\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app.kubernetes.io/name: my-service\n  template:\n    spec:\n      containers:\n        name: my-service\n        image: my-service\n        ports:\n          - containerPort: 9991\n            name: liveness-port\n            protocol: TCP\n        readinessProbe:\n          httpGet:\n            path: /readiness\n            port: liveness-port\n        livenessProbe:\n          httpGet:\n            path: /liveness\n            port: liveness-port\n        startupProbe:\n          httpGet:\n            path: /readiness\n            port: liveness-port\n```\n\nYou'll need to modify this configuration before it will work of course, replacing the image with\nyour own.\n\nConfiguring Kubernetes to make use of the probes provided by this module is a topic unto itself.\nSee\n[here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)\nfor more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoeapearson%2Felixir-k8s-probe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoeapearson%2Felixir-k8s-probe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoeapearson%2Felixir-k8s-probe/lists"}