Kubex

Kubex is the Kubernetes integration for Elixir projects and it is written in pure Elixir.

Installation

It's easy to install Kubex with hex.pm. Just add it too your dependencies and applications in your mix.exs:

defp deps do
  [
    {:kubex, "~> 0.1"}
  ]
end

def application do
  [applications: [:kubex]]
end

And then fetch your project's dependencies:

$ mix deps.get

Usage

Kubex is still very young and there is only a few use cases at the moment:

defmodule Test

  def fetch_my_pods do
    Kubex.server("https://1.2.3.4", "myuser", "mypassword")
    |> Kubex.query(:label_selector, "my=label")
    |> Kubex.get_pods
  end

  def keep_pinging_fellow_pods do
    Kubex.server_from_environment("myuser", "mypassword")
    |> Kubex.query(:label_selector, "app=elixir")
    |> Kubex.start_pinger :pinger #pinger id
  end

  def fetch_my_pods_from_env_server do
    Kubex.query(:label_selector, "my=label")
    |> Kubex.get_pods
  end

end

iex> Test.fetch_my_pods
[%{"metadata" => %{"annotations" => # ... truncated

iex> Test.keep_pinging_fellow_pods
:ok

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

fetch_my_pods_from_env_server will fetch pods from the server configured in config.exs:

config :kubex, :server,
  address: "http://1.1.1.1",
  username: "myuser",
  password: "mypass"

If no server address: is configured, then Kubix will try to resolve it from the official system environment variables.

Using :default pinger

Starting 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:

config :kubex, Kubex.Pinger,
  enable: true,
  label_selector: "app=kubex-test"

Kubex 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.

Using Kubex with :pg2

The 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.

This makes kubernetes a great elastic setup for your Elixir application, since kubernetes can scale your application live.

For at bit more info on using :pg2 with Elixir see this great blog post by Jonathan Harrington.

Testing

There 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. The integration tests a easy to run:

kubex/ > mix test

The 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:

• elixir > 1.0
• docker > 1.7
• boot2docker > 1.7 - on non-linux environments
• bash - for running test scripts

For running the test on OS X start up your terminal:

# Remember to start boot2docker
> boot2docker init # create the boot2docker vm
> boot2docker up # start the boot2docker vm
> eval '$(boot2docker shellinit)' # setup env variables for docker cli

# Create the kubernetes cluster
kubex/ > ./scripts/start_kubernetes.sh

# build the kubex test image and deploy it to local kubernetes cluster
kubex/ > ./scripts/build_and_deploy_test.sh

# using boot2docker requires a tunnel to get access to the kubernetes service and api
kubex/ > ./scripts/open_boot2docker_tunnel.sh

After opening the tunnel just open the browser at http://localhost:4000.

To clean up the test either delete all kubernetes related docker containers

> docker stop $(docker ps | grep gcr.io/ | awk '{print $1}')
> docker rm $(docker ps -a | grep gcr.io/ | awk '{print $1}')

And a few times it can help to restart boot2docker completely by removing the boo2docker vm:

> boot2docker delete

And 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.

Todo

There is much to do to make Kubex able to handle all kubernetes integration. The following is the current roadmap:

• Automated integration testing suite
• Automated build
• Full query support
• Full command support

Compability

Kubex is tested with elixir 1.0.4 and kubernetes v0.21.2 and v1.0.1.

Contributing

Please feel free to submit pull requests. Every bug fix and improvement is much appreciated. If 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.