kolm

README

kolm - Kubernetes on your local machine

kolm is a tool for running a Kubernetes 'cluster' consisting of an etcd and a kube-apiserver on your local machine. The primary use of kolm is for testing aggregated api servers, as debugging aggregated api servers in-cluster is a complex and troublesome task.

⚠️ kolm is a testing-only tool. Practices employed in this tool are inherently unsafe and should never be used in production and is plumbing-only.

Installation

To install kolm, simply run

go install github.com/onmetal/kolm/cmd/kolm@latest

👆 For now, kolm also requires etcd and kube-apiserver to be on your path. This will change in the future with automated binary management but wasn't implemented in the initial scope.

Usage

Controlling your apis

kolm has the primary type called api. An api is the previously mentioned 'cluster' with only a kube-apiserver and etcd.

The create such an api, simply run

kolm create api

This will create an api called kolm. Your kubeconfig will be modified to contain an entry pointing towards the new kolm cluster.

Once created, you can now start the api:

kolm start api

This runs the etcd and kube-apiserver. Both are running until terminated or the user interrupts via ctrl-c.

To remove an api, simply run

kolm delete api

All the previously described steps can also be done in a one-shot manner with:

kolm run api --rm

Using your api with an aggregated api server

If you have an aggregated api server & its APIServices at hand, you can let them 'join' your api. To do so, in a new terminal, first install your APIServices:

kolm apply apiservices <path-to-apiservices-directory>

Then, start your api server with flags similar to the following:

<my-server> \
  --etcd-servers=$(kolm get etcd-address) \
  --kubeconfig=$HOME/.kube/config \
  --authentication-kubeconfig=$HOME/.kube/config \
  --authorization-kubeconfig=$HOME/.kube/config \
  --tls-private-key-file $(kolm get host-key) \
  --tls-cert-file $(kolm get host-cert) \
  --secure-port=6443 \
  --feature-gates=APIPriorityAndFairness=false

After a short while, your api server should have joined the api.

Documentation

Index

• Constants
• func ExportHostCertificate(ctx context.Context, apis APIs, name string, dir string) error
• func ExportKubeconfig(ctx context.Context, apis APIs, name string, kubeCfg *clientcmdapi.Config) (*clientcmdapi.Config, error)
• func ExportKubeconfigFile(ctx context.Context, apis APIs, name, filename string) error
• func RunAPI(ctx context.Context, apis APIs, api *v1alpha1.API, opts RunAPIOptions) error
• type APIServices
• type APIs
• type Handle
• type Kolm
  • func New(dir string) (Kolm, error)
• type RunAPIOptions
• type StartOptions

Constants

const (
	DefaultName = "kolm"
)

Functions

func ExportHostCertificate

func ExportHostCertificate(ctx context.Context, apis APIs, name string, dir string) error

func ExportKubeconfig

func ExportKubeconfig(ctx context.Context, apis APIs, name string, kubeCfg *clientcmdapi.Config) (*clientcmdapi.Config, error)

func ExportKubeconfigFile

func ExportKubeconfigFile(ctx context.Context, apis APIs, name, filename string) error

func RunAPI

func RunAPI(ctx context.Context, apis APIs, api *v1alpha1.API, opts RunAPIOptions) error

Types

type APIServices

type APIServices interface {
	Apply(ctx context.Context, svcName, host string, port int32, apiServices []*apiregistrationv1.APIService) error
	Delete(ctx context.Context, svcName string) error
}

type APIs

type APIs interface {
	List(ctx context.Context) (*v1alpha1.APIList, error)
	Get(ctx context.Context, name string) (*v1alpha1.API, error)
	Create(ctx context.Context, api *v1alpha1.API) (*v1alpha1.API, error)
	Delete(ctx context.Context, name string) error

	Start(ctx context.Context, name string) (Handle, error)
	Kubeconfig(ctx context.Context, name string) (*clientcmdapi.Config, error)
	APIServices(name string) APIServices
	HostCertificate(ctx context.Context, name string) (*certutil.Pair, error)

	HostKeyFilename(ctx context.Context, name string) (string, error)
	HostCertificateFilename(ctx context.Context, name string) (string, error)
}

type Handle

type Handle interface {
	Stop() error
}

type Kolm

type Kolm interface {
	APIs() APIs
}

func New

func New(dir string) (Kolm, error)

type RunAPIOptions

type RunAPIOptions struct {
	Remove             bool
	KubeconfigFilename string
}

type StartOptions

type StartOptions struct {
	Stdout io.Writer
	Stderr io.Writer
}