client

README

About

Minimal Go Kubernetes client based on Generics

Installing

go get github.com/castai/k8s-client-go

Usage

import (
    "context"
    "log"
    "fmt"
    client "github.com/castai/k8s-client-go"
)
func main() {
	kc, err := client.NewInCluster()
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Backgroud()

	endpointsAPI := client.NewObjectAPI[corev1.Endpoints](kc)

	endpoints, err := endpointsAPI.Get(ctx, "kube-system", "kubelet", metav1.GetOptions{})
	if err != nil {
		// Handle err
		return
	}
	fmt.Printf("%+v\n", endpoints)

	events, err := endpointsAPI.Watch(ctx, "kube-system", "kubelet", metav1.ListOptions{})
	if err != nil {
		// Handle err
		return
	}
	for e := range events.ResultChan() {
		fmt.Printf("%s: %+v\n", e.Type, e.Object)
	}
}

See more in Examples

Use cases

• Embedding in Go applications for minimal binary size overhead.
• Service discovery by listing and watching endpoints. See kuberesolver as example for gRPC client side load balancing.

Documentation

Index

• type DefaultClient
  • func NewInCluster() (*DefaultClient, error)
  • func (kc *DefaultClient) APIServerURL() string
  • func (kc *DefaultClient) Do(req *http.Request) (*http.Response, error)
  • func (kc *DefaultClient) Token() string
• type DefaultLogger
  • func (l *DefaultLogger) Infof(format string, args ...any)
• type Interface
• type Logger
• type ObjectAPI
  • func NewObjectAPI[T corev1.Object](kc Interface, opt ...ObjectAPIOption) ObjectAPI[T]
• type ObjectAPIOption
  • func WithLogger(log Logger) ObjectAPIOption
  • func WithResponseDecoder(decoderFunc ResponseDecoderFunc) ObjectAPIOption
• type ObjectGetter
• type ObjectWatcher
• type ResponseDecoder
• type ResponseDecoderFunc
• type WatchInterface

Examples

• ObjectAPI

Types

type DefaultClient

type DefaultClient struct {
	HttpClient *http.Client
	// contains filtered or unexported fields
}

func NewInCluster

func NewInCluster() (*DefaultClient, error)

NewInCluster creates Client if it is inside Kubernetes.

func (*DefaultClient) APIServerURL

func (kc *DefaultClient) APIServerURL() string

func (*DefaultClient) Do

func (kc *DefaultClient) Do(req *http.Request) (*http.Response, error)

func (*DefaultClient) Token

func (kc *DefaultClient) Token() string

type DefaultLogger

type DefaultLogger struct {
}

func (*DefaultLogger) Infof

func (l *DefaultLogger) Infof(format string, args ...any)

type Interface

type Interface interface {
	// Do sends HTTP request to ObjectAPI server.
	Do(req *http.Request) (*http.Response, error)
	// Token returns current access token.
	Token() string
	// APIServerURL returns API server URL.
	APIServerURL() string
}

Interface is minimal kubernetes Client interface.

type Logger

type Logger interface {
	Infof(format string, args ...any)
}

type ObjectAPI

type ObjectAPI[T corev1.Object] interface {
	ObjectGetter[T]
	ObjectWatcher[T]
}

ObjectAPI wraps all operations on object.

Example

package main

import (
	"context"
	"fmt"

	client "github.com/castai/k8s-client-go"
	corev1 "github.com/castai/k8s-client-go/types/core/v1"
	metav1 "github.com/castai/k8s-client-go/types/meta/v1"
)

func main() {
	kc, err := client.NewInCluster()
	if err != nil {
		// Handle err
		return
	}

	ctx := context.Background()
	endpointsAPI := client.NewObjectAPI[corev1.Endpoints](kc)

	endpoints, err := endpointsAPI.Get(ctx, "kube-system", "kubelet", metav1.GetOptions{})
	if err != nil {
		// Handle err
		return
	}
	fmt.Printf("%+v\n", endpoints)

	events, err := endpointsAPI.Watch(ctx, "kube-system", "kubelet", metav1.ListOptions{})
	if err != nil {
		// Handle err
		return
	}
	for e := range events.ResultChan() {
		fmt.Printf("%s: %+v\n", e.Type, e.Object)
	}

	// Custom types
	podAPI := client.NewObjectAPI[CustomPod](kc)
	pod, err := podAPI.Get(ctx, "kube-system", "core-dns-123", metav1.GetOptions{})
	if err != nil {
		// Handle err
		return
	}
	fmt.Printf("%+v\n", pod)
}

type CustomPod struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`
}

func (p CustomPod) GetObjectMeta() metav1.ObjectMeta {
	return p.ObjectMeta
}

func (p CustomPod) GetTypeMeta() metav1.TypeMeta {
	return p.TypeMeta
}

func (p CustomPod) GVR() metav1.GroupVersionResource {
	return metav1.GroupVersionResource{
		Group:    "",
		Version:  "v1",
		Resource: "pods",
	}
}

func NewObjectAPI

func NewObjectAPI[T corev1.Object](kc Interface, opt ...ObjectAPIOption) ObjectAPI[T]

type ObjectAPIOption

type ObjectAPIOption func(opts *objectAPIOptions)

func WithLogger

func WithLogger(log Logger) ObjectAPIOption

func WithResponseDecoder

func WithResponseDecoder(decoderFunc ResponseDecoderFunc) ObjectAPIOption

type ObjectGetter

type ObjectGetter[T corev1.Object] interface {
	Get(ctx context.Context, namespace, name string, _ metav1.GetOptions) (*T, error)
}

ObjectGetter is generic object getter.

type ObjectWatcher

type ObjectWatcher[T corev1.Object] interface {
	Watch(ctx context.Context, namespace, name string, _ metav1.ListOptions) (WatchInterface[T], error)
}

ObjectWatcher is generic object watcher.

type ResponseDecoder

type ResponseDecoder interface {
	Decode(v any) error
}

ResponseDecoder allows to specify custom JSON response decoder. By default, std json decoder is used.

type ResponseDecoderFunc

type ResponseDecoderFunc func(r io.Reader) ResponseDecoder

type WatchInterface

type WatchInterface[T corev1.Object] interface {
	// Stop stops watching. Will close the channel returned by ResultChan(). Releases
	// any resources used by the Watch.
	Stop()

	// ResultChan returns a chan which will receive all the events. If an error occurs
	// or Stop() is called, this channel will be closed, in which case the
	// Watch should be completely cleaned up.
	ResultChan() <-chan corev1.Event[T]
}

WatchInterface can be implemented by anything that knows how to Watch and report changes.