# 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, "~> 2.0"}

## Usage

Check out the [Usage Guide]( for in-depth examples. If you like
learning with Livebook, check out [kino_k8s]( It comes with
nice smart cells to help you generate your first working code.

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)