Kubegen

Generate resource based Kubernetes clients with Kubegen.

Installation

kubegen is a code generator. Add the package as dev dependency. Make sure to
add kubereq to your list of dependencies as well:

def deps do
  [
    {:kubegen, "~> 0.1.2", only: :dev, runtime: false},
    {:kubereq, "~> 0.3.0"}
  ]
end

The docs can be found at https://hexdocs.pm/kubegen.

Configuration

Before you can generate clients, you need to create a configuration in your config.exs under config :kubegen, :default or config :kubegen, :mycluster. where a custom :mycluster identifier is passed as argument (mix kubegen -c mycluster)

:module_prefix - The prefix of the generated modules (e.g. MyApp.K8sClient)
:kubeconfig_pipeline - The Pluggable pipeline responsible for loading the Kubernetes config. (e.g. Kubereq.Kubeconfig.Default)
:resources - List of resources for which clients are generated.

The entries of :resources can be in the form of

Group-Version-Kind in the case of Kubernetes core resources.
Path to a local CRD YAML (multiple CRDs in one file are supported)
URL to a public remote CRD Yaml (multiple CRDs in one file are supported)

Example

config :kubegen, :default,
  module_prefix: MyApp.K8sClient,
  kubeconfig_pipeline: Kubereq.Kubeconfig.Default,
  resources: [
    "v1/ConfigMap",
    "rbac.authorization.k8s.io/v1/ClusterRole",
    "test/support/foos.example.com.yaml", # local CRD
    "https://raw.githubusercontent.com/mruoss/kompost/main/priv/manifest/postgresdatabase.crd.yaml" # public remote CRD
  ]

How to find the correct Group-Version-Kind identifier

Use mix kubegen.search to search for GVKs (e.g. mix.kubegen.search Pod)

Generate Resource Clients

Now you can (re-)generate clients using mix kubegen or mix kubegen -c mycluster

Using the generated Clients

kubegen creates a module per resource and subresource. Each resource is generaated with functions for the operations applicable to that resource. The generated functions also come with @doc documentations.

ConfigMap Example

You can use apply/3 or create/2 to create a new resource:

import YamlElixir.Sigil
alias MyApp.K8sClient.Core.V1.ConfigMap

ConfigMap.apply(~y"""
apiVersion: v1
kind: ConfigMap
metadata:
  namespace: default
  name: my-config
  labels:
    app: my-app
data:
  foo: bar
""")

To retrieve a resource, use get/2:

ConfigMap.get("default", "my-config")

Use list/0 or list/1 to list resources of that kind in all namespaces or list/2 to list resources in a specific namespace. Label or field selectors can be passed as option if needed.

ConfigMap.list("default", label_selectors: [{"app", "my-app"}])

delete/2 and delete_all/2 delete a single or multiple resources (whereas the latter also supports selectors).

ConfigMap.delete("default", "my-config")
ConfigMap.delete_all("default", label_selectors: [{"app", "my-app"}])

There are more functions like update/1, json_path/3, merge_patch/3, watch/N, watch_single/3 wait_until/4. Checkout the generated modules for their documentation.

mruoss/kubegen