pk8s

README

pk8s

!IN DEVELOPMENT!

pk8s (Programmable Kubernetes) is a software development framework designed to facilitate the creation of Kubernetes manifests. It allows developers to define, manage, and reuse Kubernetes manifests programmatically, enhancing efficiency and maintainability.

Concepts

pk8s applications are developed using the Go programming language.

At the core of a pk8s project is the App, which serves as the foundational element. Within an App, users have the flexibility to define multiple Stack, representing various environments, clusters, or team. Each Stack can further encapsulate multiple Chart, which are organized collections of Kubernetes resources such as Deployment, Service, Ingress, ReplicaSet, and more.

Using

CLI

The easiest way to get started is using the CLI.

Quickstart

Install:

go install github.com/alexferl/pk8s/pk8s@latest

Init:

pk8s init infra

Output:

  Your pk8s Go project is ready! 🚀✨

    📤 pk8s export  Export Kubernetes manifests to dist/
    📥 pk8s import  Import custom resource definitions to imports/

  Deploy:
    🛠️ kubectl apply -f dist/

Change directory:

cd infra

Export:

pk8s export

Output:

Generated Kubernetes manifests:
  dev:
    - dist/dev/hello.yaml

And if you check the content of dist/dev/hello.yaml:

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-24cf642e

Note: the apiVersion and kind fields are automatically populated on generation for resources that require them.

You can now edit main.go and add more stacks and charts and repeat the export process to generate new manifests.

Code

If you can't or don't want to use the CLI, you can also directly use the library.

Quickstart

Install:

go get github.com/alexferl/pk8s

Create a main.go file with the following content:

package main

import (
	"github.com/alexferl/pk8s"
	"github.com/alexferl/pk8s/k8s"
)

type ChartParams struct {
	pk8s.ChartParams
}

func NewChart(stack *pk8s.Stack, name string, params *ChartParams) *pk8s.Chart {
	var chartParams pk8s.ChartParams
	if params != nil {
		chartParams = params.ChartParams
	}
	chart := pk8s.NewChart(stack, name, &chartParams)

	deployment := &k8s.DeploymentV1{
		// ...
	}

	chart.Append(deployment)

	return chart
}

func main() {
	app := pk8s.New()
	stack := pk8s.NewStack(app, "dev")

	NewChart(stack, "hello", nil)

	app.Export()
}

Run it:

go run main.go

Output:

Generated Kubernetes manifests:
  dev:
    - dist/dev/hello.yaml

Examples

See the examples directory for more complex examples.

FAQ

1. Who is this for?
   • Software developers, DevOps engineers, and Kubernetes users who prefer defining Kubernetes resources programmatically rather than using YAML.
2. Why not just use cdk8s?
   • cdk8s is a robust tool for managing Kubernetes configurations, but its CLI depends on Node.js since it is fundamentally a JavaScript-based project. While it provides bindings for other languages, such as Go, the generated code may occasionally result in less elegant and idiomatic implementations in those languages.

Documentation

Index

• Variables
• func InitLog()
• type APIObject
  • func (a *APIObject) JSON() ([]byte, error)
  • func (a *APIObject) String() string
  • func (a *APIObject) YAML() ([]byte, error)
• type App
  • func New() *App
  • func NewWithConfig(config AppConfig) *App
  • func (a *App) Export()
  • func (a *App) Print()
  • func (a *App) String() string
• type AppConfig
• type CRD
• type Chart
  • func NewChart(s *Stack, name string, params *ChartParams) *Chart
  • func (c *Chart) Append(objs ...any)
  • func (c *Chart) String() string
• type ChartParams
• type File
  • func (f *File) String() string
  • func (f *File) WriteString(s string)
• type GroupItems
• type Importer
  • func NewImporter(config *ImporterConfig) Importer
• type ImporterConfig
• type Names
• type Property
• type Spec
• type Stack
  • func NewStack(app *App, name string) *Stack
  • func (s *Stack) String() string
• type Version

Variables

var DefaultConfig = AppConfig{
	OutputPath:          k8s.String("dist"),
	OutputFileExtension: k8s.String(".yaml"),
}

Functions

func InitLog

func InitLog()

Types

type APIObject

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

func (*APIObject) JSON

func (a *APIObject) JSON() ([]byte, error)

JSON returns the JSON encoding of the API object.

func (*APIObject) String

func (a *APIObject) String() string

String returns a YAML string of the API object.

func (*APIObject) YAML

func (a *APIObject) YAML() ([]byte, error)

YAML returns the YAML encoding of the API object.

type App

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

func New

func New() *App

func NewWithConfig

func NewWithConfig(config AppConfig) *App

func (*App) Export

func (a *App) Export()

Export exports all manifests to the output directory.

func (*App) Print

func (a *App) Print()

Print prints all YAML objects across all stacks and charts in this app.

func (*App) String

func (a *App) String() string

String returns all YAML objects across all stacks and charts in this app.

type AppConfig

type AppConfig struct {
	// OutputPath defines the directory to export to.
	// Optional. Default: "dist".
	OutputPath *string

	// OutputFileExtension defines the file extension to use for generated YAML files.
	// Optional. Default: ".yaml".
	OutputFileExtension *string
}

type CRD

type CRD struct {
	Spec Spec `yaml:"spec"`
}

type Chart

type Chart struct {
	Name      string
	Namespace string
	Params    *ChartParams
	// contains filtered or unexported fields
}

func NewChart

func NewChart(s *Stack, name string, params *ChartParams) *Chart

func (*Chart) Append

func (c *Chart) Append(objs ...any)

Append appends k8s objects.

func (*Chart) String

func (c *Chart) String() string

type ChartParams

type ChartParams struct {
	// DisableNameHashes removes the generated stable hash that is suffixed to the resource name.
	// Optional. Default: false.
	DisableNameHashes bool

	// Labels to apply to all the resources in this chart.
	// Optional. Default: nil.
	Labels *map[string]string

	// Namespace to apply to all the resources in this chart. This will only apply to objects that don't have a
	// namespace already defined on them.
	// Optional. Default: nil. (usually means "default" in Kubernetes)
	Namespace *string
}

type File

type File struct {
	Body    string
	Dir     string
	Imports []string
	Name    string
	Package string
	// contains filtered or unexported fields
}

func (*File) String

func (f *File) String() string

func (*File) WriteString

func (f *File) WriteString(s string)

type GroupItems

type GroupItems struct {
	Group string
	Items []string
}

type Importer

type Importer interface {
	Read(path string) ([]byte, error)
	Import(data []byte) error
}

func NewImporter

func NewImporter(config *ImporterConfig) Importer

type ImporterConfig

type ImporterConfig struct {
	Overwrite bool
}

type Names

type Names struct {
	Kind     string `yaml:"kind"`
	ListKind string `yaml:"listKind"`
	Singular string `yaml:"singular"`
}

type Property

type Property struct {
	Type        string              `yaml:"type"`
	Description string              `yaml:"description,omitempty"`
	Properties  map[string]Property `yaml:"properties,omitempty"`
	Items       *Property           `yaml:"items,omitempty"`
	Required    []string            `yaml:"required,omitempty"`
}

type Spec

type Spec struct {
	Group    string    `yaml:"group"`
	Names    Names     `yaml:"names"`
	Versions []Version `yaml:"versions"`
}

type Stack

type Stack struct {
	Name string
	// contains filtered or unexported fields
}

func NewStack

func NewStack(app *App, name string) *Stack

func (*Stack) String

func (s *Stack) String() string

String returns a string of all YAML objects across all charts in this stack.

type Version

type Version struct {
	Schema struct {
		OpenAPIV3Schema Property `yaml:"openAPIV3Schema"`
	} `yaml:"schema"`
}