# K8s

[![Module Version](](
[![Coverage Status](](
[![Last Updated](](

[![Build Status CI](](
[![Build Status Elixir](](
[![Build Status K8s](](

[![Hex Docs](](
[![Total Download](](

[K8s]( - Kubernetes API Client for Elixir

## Features

* A client API for humans 👩đŸŧ🧑👩đŸģ👩đŸŊ👩🏾🧑đŸģ🧑đŸŊ🧑🧑🏾👨đŸŧ👨🏾👨đŸŋ
* 🔮 Kubernetes resources, groups, and CRDs are autodiscovered at boot time. No swagger file to include or override.
* Client supports standard HTTP calls, async batches, wait on status ⏲ī¸, and watchers 👀
* ⚙ī¸ HTTP Request middleware
* Multiple clusters ⚓ ⚓ ⚓
* 🔐 Multiple authentication credentials
  * 🤖 serviceaccount
  * token
  * 📜 certificate
  * auth-provider
  * Pluggable auth providers!
* 🆗 Tested against Kubernetes versions 1.10+ and master
* 🛠ī¸ CRD support
* 📈 Integrated with `:telemetry`
* ℹī¸ Kubernetes resource and version helper functions
* 🧰 Kube config file parsing
* 🏎ī¸ Macro free; fast compile & fast startup

## Installation

The package can be installed by adding `:k8s` to your list of dependencies in `mix.exs`:

def deps do
    {:k8s, "~> 1.0"}

## Usage

Check out the [Usage Guide]( for in-depth examples.

Most functions are also written using doctests.

* [K8s.Client doctests](
* [K8s.Conn doctests](
* [K8s.Resource doctests](
* [K8s.Version doctests](

If you are interested in building Kubernetes Operators or Schedulers, check out [Bonny](

## tl;dr Examples

### Configure a cluster connection

Cluster connections can be created using the `K8s.Conn` module. 

`K8s.Conn.from_file/1` will use the current context in your kubeconfig.

{:ok, conn} = K8s.Conn.from_file("path/to/kubeconfig.yaml")

`K8s.Conn.from_file/2` accepts a keyword list to set the `:user`, `:cluster`, and/or `:context`

Connections can also be created in-cluster from a service account.

{:ok, conn} = K8s.Conn.from_service_account("/path/to/service-account/directory")

Check out the [connection guide]( for additional details.

### Creating a deployment

{:ok, conn} = K8s.Conn.from_file("path/to/kubeconfig.yaml")

opts = [namespace: "default", name: "nginx", image: "nginx:nginx:1.7.9"]
{:ok, resource} = K8s.Resource.from_file("priv/deployment.yaml", opts)

operation = K8s.Client.create(resource)
{:ok, deployment} =, operation)

### Listing deployments

In a namespace:

{:ok, conn} = K8s.Conn.from_file("path/to/kubeconfig.yaml")

operation = K8s.Client.list("apps/v1", "Deployment", namespace: "prod")
{:ok, deployments} =, operation)

Across all namespaces:

{:ok, conn} = K8s.Conn.from_file("path/to/kubeconfig.yaml")

operation = K8s.Client.list("apps/v1", "Deployment", namespace: :all)
{:ok, deployments} =, operation)

### Getting a deployment

{:ok, conn} = K8s.Conn.from_file("path/to/kubeconfig.yaml")

operation = K8s.Client.get("apps/v1", :deployment, [namespace: "default", name: "nginx-deployment"])
{:ok, deployment} =, operation)