{"id":13507578,"url":"https://github.com/ingerslevio/kubex","last_synced_at":"2025-10-21T15:50:33.429Z","repository":{"id":57514284,"uuid":"39970528","full_name":"ingerslevio/kubex","owner":"ingerslevio","description":"Kubex is the kubernetes integration for Elixir projects and it is written in pure Elixir.","archived":false,"fork":false,"pushed_at":"2015-08-03T11:14:32.000Z","size":103,"stargazers_count":38,"open_issues_count":1,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-22T00:56:55.027Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ingerslevio.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2015-07-30T20:18:00.000Z","updated_at":"2023-09-01T11:27:03.000Z","dependencies_parsed_at":"2022-08-31T23:01:06.658Z","dependency_job_id":null,"html_url":"https://github.com/ingerslevio/kubex","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingerslevio%2Fkubex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingerslevio%2Fkubex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingerslevio%2Fkubex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingerslevio%2Fkubex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ingerslevio","download_url":"https://codeload.github.com/ingerslevio/kubex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246301963,"owners_count":20755512,"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","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":[],"created_at":"2024-08-01T02:00:36.448Z","updated_at":"2025-10-21T15:50:28.389Z","avatar_url":"https://github.com/ingerslevio.png","language":"Elixir","funding_links":[],"categories":["Cloud Infrastructure and Management"],"sub_categories":[],"readme":"# Kubex [![hex.pm version](https://img.shields.io/hexpm/v/kubex.svg?style=flat)](https://hex.pm/packages/kubex) [![hex.pm downloads](https://img.shields.io/hexpm/dt/kubex.svg?style=flat)](https://hex.pm/packages/kubex)\n\nKubex is the [Kubernetes](http://kubernetes.io/) integration for Elixir projects and it is written in pure Elixir.\n\n## Installation\n\nIt's easy to install Kubex with [hex.pm](https://hex.pm). Just add it too your dependencies and applications in your `mix.exs`:\n\n```elixir\ndefp deps do\n  [\n    {:kubex, \"~\u003e 0.1\"}\n  ]\nend\n\ndef application do\n  [applications: [:kubex]]\nend\n```\n\nAnd then fetch your project's dependencies:\n\n```bash\n$ mix deps.get\n```\n\n## Usage\n\nKubex is still very young and there is only a few use cases at the moment:\n\n```elixir\ndefmodule Test\n\n  def fetch_my_pods do\n    Kubex.server(\"https://1.2.3.4\", \"myuser\", \"mypassword\")\n    |\u003e Kubex.query(:label_selector, \"my=label\")\n    |\u003e Kubex.get_pods\n  end\n\n  def keep_pinging_fellow_pods do\n    Kubex.server_from_environment(\"myuser\", \"mypassword\")\n    |\u003e Kubex.query(:label_selector, \"app=elixir\")\n    |\u003e Kubex.start_pinger :pinger #pinger id\n  end\n\n  def fetch_my_pods_from_env_server do\n    Kubex.query(:label_selector, \"my=label\")\n    |\u003e Kubex.get_pods\n  end\n\nend\n```\n\n```elixir\niex\u003e Test.fetch_my_pods\n[%{\"metadata\" =\u003e %{\"annotations\" =\u003e # ... truncated\n\niex\u003e Test.keep_pinging_fellow_pods\n:ok\n```\n\n`fetch_my_pods` will return the full output from kubernetes api deserialized with `Poison`. The other method `keep_pinging_fellow_pods` will start a _pinger_ which keeps pinging nodes retreived from the kubernetes API. This will make nodes aware of each other. This is discussed further in **Using Kubex with `:pg2`**\n\n`fetch_my_pods_from_env_server` will fetch pods from the server configured in `config.exs`:\n\n```elixir\nconfig :kubex, :server,\n  address: \"http://1.1.1.1\",\n  username: \"myuser\",\n  password: \"mypass\"\n```\n\nIf no server `address:` is configured, then Kubix will try to resolve it from the official system environment variables.\n\n## Using `:default` pinger\nStarting from version 0.1.1 of kubex it is possible to use the `:default` pinger, which is setup through config. Add the following to `config.exs`:\n\n```elixir\nconfig :kubex, Kubex.Pinger,\n  enable: true,\n  label_selector: \"app=kubex-test\"\n```\n\nKubex will with this setup keep pinging all pods from the kubernetes server fetched from the official system environment variables. The default pinger will, like the other queries, use the configured server address and authentication.\n\n## Using Kubex with `:pg2`\nThe continuously pinging functionality built into Kubex is a perfect tool for using `:pg2`, kubernetes and Elixir. Hosting two nodes in kubernetes with the pinger enabled will make all nodes know about each other, thus _synchronize_ `:pg2` groups between each nodes.\n\nThis makes kubernetes a great elastic setup for your Elixir application, since kubernetes can scale your application live.\n\nFor at bit more info on using `:pg2` with Elixir see [this great blog post](http://blog.jonharrington.org/elixir-and-docker/) by Jonathan Harrington.\n\n## Testing\nThere are two kind of tests for Kubex; a set of integration tests of the query system with a mocked kubernetes API and a set of full system tests with deployed docker images running an app with Kubex.\nThe integration tests a easy to run:\n\n```bash\nkubex/ \u003e mix test\n```\n\nThe system tests run in a local kubetnetes cluster. These tests has been run on a OS X with boot2docker, but it should run mostly anywhere with the following requirements:\n\n* elixir `\u003e 1.0`\n* docker `\u003e 1.7`\n* boot2docker `\u003e 1.7` - on non-linux environments\n* bash - for running test scripts\n\nFor running the test on OS X start up your terminal:\n\n```bash\n# Remember to start boot2docker\n\u003e boot2docker init # create the boot2docker vm\n\u003e boot2docker up # start the boot2docker vm\n\u003e eval '$(boot2docker shellinit)' # setup env variables for docker cli\n\n# Create the kubernetes cluster\nkubex/ \u003e ./scripts/start_kubernetes.sh\n\n# build the kubex test image and deploy it to local kubernetes cluster\nkubex/ \u003e ./scripts/build_and_deploy_test.sh\n\n# using boot2docker requires a tunnel to get access to the kubernetes service and api\nkubex/ \u003e ./scripts/open_boot2docker_tunnel.sh\n```\n\nAfter opening the tunnel just open the browser at [http://localhost:4000](http://localhost:4000).\n\nTo clean up the test either delete all kubernetes related docker containers\n\n```bash\n\u003e docker stop $(docker ps | grep gcr.io/ | awk '{print $1}')\n\u003e docker rm $(docker ps -a | grep gcr.io/ | awk '{print $1}')\n```\n\nAnd a few times it can help to restart boot2docker completely by removing the boo2docker vm:\n\n```bash\n\u003e boot2docker delete\n```\n\nAnd then just start over. For testing on linux environment it should be the same as above, but just leave out all tunnel and boot2docker related commands.\n\n## Todo\n\nThere is much to do to make Kubex able to handle all kubernetes integration. The following is the current roadmap:\n\n* [ ] Automated integration testing suite\n* [ ] Automated build\n* [ ] Full query support\n* [ ] Full command support\n\n## Compability\nKubex is tested with elixir 1.0.4 and kubernetes v0.21.2 and v1.0.1.\n\n## Contributing\n\nPlease feel free to submit pull requests. Every bug fix and improvement is much appreciated.\nIf you have found a bug or have an idea, but don't know how to solve it or make it, you're welcome to open an issue, but please check if there is an issue registered already first.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fingerslevio%2Fkubex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fingerslevio%2Fkubex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fingerslevio%2Fkubex/lists"}