pods

README

📦 Pods

High-level K8s API for developer envnrionments.

Why

This framework introduces a lightweight abstraction layer, allowing developers to focus on product configuration while abstracting away Kubernetes complexities. It meant to be used with CTFv2 framework to run components on K8s.

Real world example (Chainlink Node Set)

In this example we'll spin up a local Kind cluster and deploy a Chainlink cluster, just 40 lines of code (without product configuration).

Follow the README

Developing

Install pre-commit hooks and check available actions (lint, test ,etc)

just install
just

Add new features to pods.go, add new tests to pods_test.go and make pre-commit hooks and then CI pass.

Run just test-deploy-cover to check coverage.

Create additional directories for product-specific deployments if needed.

Documentation

Index

• Constants
• Variables
• func EnvsFromMap(envVars map[string]string) []v1.EnvVar
• func K8sEnabled() bool
• func NewKubernetesClient() (*kubernetes.Clientset, error)
• func Ptr[T any](value T) *T
• func Resources(cpu, mem string) map[string]string
• func ResourcesLarge() map[string]string
• func ResourcesMedium() map[string]string
• func ResourcesSmall() map[string]string
• func Run(ctx context.Context, cfg *Config) (string, error)
• func SizedVolumeClaim(size string) []v1.PersistentVolumeClaim
• func SortedKeys(m map[string]string) []string
• func WaitReady(ctx context.Context, t time.Duration) error
• type API
  • func NewAPI(namespace string) (*API, error)
  • func (k *API) AllPodsReady(ctx context.Context) (bool, error)
  • func (k *API) CreateNamespace(ctx context.Context, name string) error
  • func (k *API) GetPods(ctx context.Context) (*corev1.PodList, error)
  • func (k *API) RemoveNamespace(name string) error
• type App
  • func (n *App) Manifest() string
• type Config
• type PodConfig
• type PortForwardConfig
• type PortForwardManager
  • func NewForwarder(api *API) *PortForwardManager
  • func (m *PortForwardManager) Forward(configs []PortForwardConfig) error
  • func (m *PortForwardManager) List() []string
  • func (m *PortForwardManager) Stop(serviceName string, localPort int)
  • func (m *PortForwardManager) StopAll()

Constants

const (
	RetryDelay    = 1 * time.Second
	K8sAPITimeout = 2 * time.Minute
)

const (
	ManifestsDir       = "pods-out"
	K8sNamespaceEnvVar = "KUBERNETES_NAMESPACE"
)

const (
	EnvVarLogLevel = "PODS_LOG_LEVEL"
)

Variables

var (
	L zerolog.Logger
)

Functions

func EnvsFromMap

func EnvsFromMap(envVars map[string]string) []v1.EnvVar

func K8sEnabled

func K8sEnabled() bool

func NewKubernetesClient

func NewKubernetesClient() (*kubernetes.Clientset, error)

NewKubernetesClient creates a new Kubernetes client

func Ptr

func Ptr[T any](value T) *T

func Resources

func Resources(cpu, mem string) map[string]string

func ResourcesLarge

func ResourcesLarge() map[string]string

ResourcesLarge returns large resource limits/requests

func ResourcesMedium

func ResourcesMedium() map[string]string

ResourcesMedium returns medium resource limits/requests

func ResourcesSmall

func ResourcesSmall() map[string]string

ResourcesSmall returns small resource limits/requests

func Run

func Run(ctx context.Context, cfg *Config) (string, error)

Run generates and applies a new K8s YAML manifest

func SizedVolumeClaim

func SizedVolumeClaim(size string) []v1.PersistentVolumeClaim

func SortedKeys

func SortedKeys(m map[string]string) []string

SortedKeys returns sorted keys of a map

func WaitReady

func WaitReady(ctx context.Context, t time.Duration) error

Types

type API

type API struct {
	ClientSet  *kubernetes.Clientset
	RESTConfig *rest.Config
	// contains filtered or unexported fields
}

API is a struct that provides methods to interact with Kubernetes clusters.

var Client *API

Client is a global K8s client that we use for all deployments

func NewAPI

func NewAPI(namespace string) (*API, error)

NewAPI creates a new instance of K8s API. It takes the kubeconfig path and namespace as parameters.

func (*API) AllPodsReady

func (k *API) AllPodsReady(ctx context.Context) (bool, error)

AllPodsReady checks if all Pods in the namespace are ready. A Pod is considered ready if all its containers are ready and the Pod's phase is "Running".

func (*API) CreateNamespace

func (k *API) CreateNamespace(ctx context.Context, name string) error

CreateNamespace creates a new Kubernetes namespace with the specified name.

func (*API) GetPods

func (k *API) GetPods(ctx context.Context) (*corev1.PodList, error)

GetPods returns a list of Pods in the specified namespace.

func (*API) RemoveNamespace

func (k *API) RemoveNamespace(name string) error

RemoveNamespace deletes a Kubernetes namespace with the specified name.

type App

type App struct {
	// contains filtered or unexported fields
}

App is an application context with generated manifests

func (*App) Manifest

func (n *App) Manifest() string

Manifest returns current generated YAML manifest

type Config

type Config struct {
	Namespace string
	Pods      []*PodConfig
}

Config describes Pods library configuration

type PodConfig

type PodConfig struct {
	StatefulSet bool
	// Name is a pod name
	Name *string
	// Replicas amount of replicas for a pod
	Replicas *int32
	// Labels are K8s labels added to a pod
	Labels map[string]string
	// Annotations are K8s annotations added to a pod
	Annotations map[string]string
	// Image docker image URI in format $repo/$image_name:$tag, ex. "public.ecr.aws/chainlink/chainlink:v2.17.0"
	Image *string
	// Env represents container environment variables
	Env []corev1.EnvVar
	// Command is a container command to run on start
	Command *string
	// Ports is a list of $svc:$container ports, ex.: ["8080:80", "9090:90"]
	Ports []string
	// ConfigMap is a map of files in ConfigMap, ex.: "config.toml": `some_toml`
	ConfigMap map[string]string
	// ConfigMapMountPath mounts files with paths, ex.: "config.toml": "/config.toml"
	ConfigMapMountPath map[string]string
	// Secrets is a map of files in K8s Secret, ex. "secrets.toml": `some_secret`
	Secrets map[string]string
	// SecretsMountPath mounts secrets with paths, ex.: "secrets.toml": "/secrets.toml"
	SecretsMountPath map[string]string
	// ReadinessProbe is container readiness probe definition
	ReadinessProbe *corev1.Probe
	// Requests is K8s resources requests on CPU/Mem
	Requests map[string]string
	// Limits is K8s resources limits on CPU/Mem
	Limits map[string]string
	// ContainerSecurityContext is a container security context
	ContainerSecurityContext *corev1.SecurityContext
	// PodSecurityContext is a Pod security context
	PodSecurityContext *corev1.PodSecurityContext
	// VolumeClaimTemplates is a list K8s persistent volume claim templates
	VolumeClaimTemplates []corev1.PersistentVolumeClaim
}

PodConfig describes particular Pod configuration

type PortForwardConfig

type PortForwardConfig struct {
	ServiceName   string
	LocalPort     int
	ContainerPort int
	Namespace     string
}

PortForwardConfig represents a single port forward configuration

type PortForwardManager

type PortForwardManager struct {
	// contains filtered or unexported fields
}

PortForwardManager manages multiple port forwards

func NewForwarder

func NewForwarder(api *API) *PortForwardManager

NewForwarder creates a new manager for multiple port forwards

func (*PortForwardManager) Forward

func (m *PortForwardManager) Forward(configs []PortForwardConfig) error

Forward starts multiple port forwards concurrently

func (*PortForwardManager) List

func (m *PortForwardManager) List() []string

List returns all active port forwards

func (*PortForwardManager) Stop

func (m *PortForwardManager) Stop(serviceName string, localPort int)

Stop stops a specific port forward

func (*PortForwardManager) StopAll

func (m *PortForwardManager) StopAll()

StopAll stops all active port forwards