naml

README

Not Another Markup Language.

NAML is a Go library and command line tool that can be used as a framework to develop and deploy Kubernetes applications.

Replace Kubernetes YAML with raw Go!

Say so long 👋 to YAML and start using the Go 🎉 programming language to represent and deploy applications with Kubernetes.

Kubernetes applications are complicated, so lets use a proper Turing complete language to reason about them.

✅ Take advantage of all the lovely features of Go (Syntax highlighting, Cross compiling, Code generation, Documentation)

✅ Test your code directly in local Kubernetes using kind. Yes you can really deploy your applications to Kubernetes.

✅ Get your application directly into Go instead of YAML and use it in controllers, operators, CRs/CRDs easily. Use the Go compiler to your advantage.

Convert YAML to Go

cat deploy.yaml | naml codify > main.go

Turn existing YAML into formatted and syntactically correct Go that implements the Deployable interface.

mkdir out

# Get started quickly with all objects in a namespace
kubectl get all -n default -o yaml | naml codify > out/main.go

# Overload the template with your information
cat app.yaml | naml codify \
  --author-name="Charlie" \
  --author-email="<charlie@nivenly.com>" > out/main.go
  
# Combine files in one command
printf "\n\n---\n\n" | cat file1.yaml - file2.yaml - file3.yaml | naml codify > out/main.go

Then compile and run your application against Kubernetes.

cd out
naml build -o app
./app -o yaml
./app install 
./app uninstall

Use make help for more. Happy coding 🎉.

Example Projects

There is a "repository" of examples to borrow/fork:

• simple quick and simple example.
• examples GitHub organization.

The Deployable Interface

As long as there is a Go system that implements this interface it can be used with naml. See examples for how to include an implementation in your project.

// Deployable is an interface that can be implemented
// for deployable applications.
type Deployable interface {

// Install will attempt to install in Kubernetes
Install(client kubernetes.Interface) error

// Uninstall will attempt to uninstall in Kubernetes
Uninstall(client kubernetes.Interface) error

// Meta returns a NAML Meta structure which embed Kubernetes *metav1.ObjectMeta
Meta() *AppMeta

// Objects will return the runtime objects defined for each application
Objects() []runtime.Object
}

In order to get the raw Kubernetes objects in Go without installing them anywhere, you pass in nil in place of an authenticated Kubernetes Clientset.

Then you can access the objects in memory.

    app.Install(nil)
    objects := app.Objects()

Nothing fancy

There isn't anything special here. 🤷‍♀ We use the same client the rest of Kubernetes does.

❎ No new complex tools.

❎ No charts.

❎ No templating at runtime.

❎ No vague error messages.

❎ No more YAML guessing/checking.

✅ Just Go. 🎉

Features

• Express applications in 🎉 Go instead of YAML.
• Use the Go compiler to check your syntax.
• Write real tests 🤓 using Go to check and validate your deployments.
• Test your applications in Kubernetes using kind.
• Define custom installation logic. What happens if it fails? What about logical concerns at runtime?
• Define custom application registries. Multiple apps of the same flavor? No problem.
• Use the latest client (the same client the rest of Kubernetes uses).

Documentation

Index

• Constants
• Variables
• func AllInit(kubeConfigPath string, verbose bool, with []string) error
• func Banner()
• func BusyboxDeployment(name string) *v1.Deployment
• func Client() (*kubernetes.Clientset, error)
• func ClientFromFlags(apiUrl, kubeConfigPath string) (*kubernetes.Clientset, error)
• func ClientFromPath(kubeConfigPath string) (*kubernetes.Clientset, error)
• func Codify(input io.Reader, v *CodifyValues) ([]byte, error)
• func Install(app Deployable) error
• func List()
• func PrintJSON(app Deployable) error
• func PrintKubeYAML(app Deployable) error
• func PrintObjects(app Deployable)
• func ReaderToBytes(input io.Reader) ([]byte, error)
• func Register(app Deployable)
• func RegisterAndError(app Deployable) error
• func RegisterAndExit(app Deployable)
• func Registry() map[string]Deployable
• func RunCommandLine() error
• func RunCommandLineAndExit()
• func RunCommandLineWithOptions() error
• func RunOutput(appName string, o OutputEncoding) error
• func Src(path string) ([]byte, error)
• func TestClusterKubeConfigPath() string
• func TestClusterStart() error
• func TestClusterStop() error
• func Uninstall(app Deployable) error
• type AppMeta
• type CodifyObject
  • func ReaderToCodifyObjects(input io.Reader) ([]CodifyObject, int, error)
• type CodifyValues
• type Deployable
  • func Find(name string) Deployable
• type OutputEncoding
• type Program
  • func Compile(src []byte) (*Program, error)
  • func (p *Program) Execute(flags []string) (*bytes.Buffer, *bytes.Buffer, error)
  • func (p *Program) Remove() error
• type Source

Constants

const (
	KubeconfigEnvironmentalVariable = "KUBECONFIG"
	KubeconfigDefaultDirectory      = ".kube"
	KubeconfigDefaultFile           = "config"
)

const (
	// TestClusterName is used to identify the test cluster with Kind.
	TestClusterName string = "namltestcluster"
)

const (

	// YAMLDelimiter is the official delimiter used to append multiple
	// YAML files together into the same file.
	//
	//	Reference: https://yaml.org/spec/1.2/spec.html
	//
	YAMLDelimiter string = "\n---\n"
)

Variables

var (

	//go:embed src/main.go.tpl
	FormatMainGo string

	//go:embed src/library.go.tpl
	FormatLibraryGo string
)

var Version string = "1.0.1"

Version is this specific version on naml

Functions

func AllInit

func AllInit(kubeConfigPath string, verbose bool, with []string) error

AllInit is the "constructor" for every command line flag. This is how we use naml -w to include sub-namls

func Banner

func Banner()

func BusyboxDeployment

func BusyboxDeployment(name string) *v1.Deployment

BusyboxDeployment is useful for quick testing and debugging. This is broken by design.

func Client

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

Client is used to authenticate with Kubernetes and build the Kube client for the rest of the program.

func ClientFromFlags

func ClientFromFlags(apiUrl, kubeConfigPath string) (*kubernetes.Clientset, error)

ClientFromFlags will plumb well-known command line flags through to the kubeconfig

func ClientFromPath

func ClientFromPath(kubeConfigPath string) (*kubernetes.Clientset, error)

ClientFromPath is used to authenticate with Kubernetes and build the Kube client for the rest of the program given a specific kube config path.

Useful for testing.

func Codify

func Codify(input io.Reader, v *CodifyValues) ([]byte, error)

Codify will take any valid Kubernetes YAML as an io.Reader and do it's best to return a syntactically correct Go program that is NAML compliant.

The NAML codebase is Apache 2.0 licensed, so we assume that any calling code will adopt the same Apache license.

func Install

func Install(app Deployable) error

Install is used to install an application in Kubernetes

func List

func List()

List the naml package information in stdout

func PrintJSON

func PrintJSON(app Deployable) error

func PrintKubeYAML

func PrintKubeYAML(app Deployable) error

func PrintObjects

func PrintObjects(app Deployable)

func ReaderToBytes

func ReaderToBytes(input io.Reader) ([]byte, error)

ReaderToBytes is basically a wrapper for ReadAll, however we add in some specific error language for stdin.

func Register

func Register(app Deployable)

Register an application with naml

func RegisterAndError

func RegisterAndError(app Deployable) error

func RegisterAndExit

func RegisterAndExit(app Deployable)

RegisterAndExit will register the app or exit with an error message in stdout

func Registry

func Registry() map[string]Deployable

Registry will return the registry

func RunCommandLine

func RunCommandLine() error

RunCommandLine is the global NAML command line program.

Use this if you would like to use the built in NAML command line interface.

func RunCommandLineAndExit

func RunCommandLineAndExit()

func RunCommandLineWithOptions

func RunCommandLineWithOptions() error

RunCommandLineWithOptions is here so we can default values in RunCommandLine() that we would want to pass in here later (tests, etc)

func RunOutput

func RunOutput(appName string, o OutputEncoding) error

func Src

func Src(path string) ([]byte, error)

func TestClusterKubeConfigPath

func TestClusterKubeConfigPath() string

TestClusterKubeConfigPath will export the kubeconfig path to this directory to use for the client in the tests.

func TestClusterStart

func TestClusterStart() error

TestClusterStart can be used to start the test cluster in the TestMain() function.

func TestClusterStop

func TestClusterStop() error

TestClusterStop can be used to stop the test cluster in the TestMain() function.

func Uninstall

func Uninstall(app Deployable) error

Uninstall is used to uninstall an application in Kubernetes

Types

type AppMeta

type AppMeta struct {
	Description string
	metav1.ObjectMeta
}

type CodifyObject

type CodifyObject interface {

	// Install returns the snippet of code that would
	// traditionally live inside a function. This
	// will define literally (what it can) a struct
	// for the object, and pass it to the corresponding
	// kubernetes library.
	Install() (string, []string)

	// Uninstall is the reverse library call of install.
	Uninstall() string
}

func ReaderToCodifyObjects

func ReaderToCodifyObjects(input io.Reader) ([]CodifyObject, int, error)

ReaderToCodifyObjects will convert an io.Reader to naml compatible Go objects.

This function works by doing the best it can, and will return as many CodifyObjects as possible. The function will return a positive integer for every YAML object it detects, that it is unable to Codify. If the delta is greater than 0, that means we have encountered a loss.

type CodifyValues

type CodifyValues struct {
	LibraryMode   bool
	AuthorName    string
	AuthorEmail   string
	CopyrightYear string
	AppNameTitle  string
	AppNameLower  string
	Description   string
	Version       string
	Install       string
	Uninstall     string
	Packages      string
	PackageName   string
}

CodifyValues are ultimately what is rendered into the .naml files in /src. These values are what will be created in the output.

type Deployable

type Deployable interface {

	// Install will attempt to install in Kubernetes
	Install(client kubernetes.Interface) error

	// Uninstall will attempt to uninstall in Kubernetes
	Uninstall(client kubernetes.Interface) error

	// Meta returns a NAML Meta structure which embed Kubernetes *metav1.ObjectMeta
	Meta() *AppMeta

	// Objects will return the runtime objects defined for each application
	Objects() []runtime.Object
}

Deployable is an interface that can be implemented for deployable applications.

func Find

func Find(name string) Deployable

Find an application by name

type OutputEncoding

type OutputEncoding int

const (
	OutputYAML OutputEncoding = 0
	OutputJSON OutputEncoding = 1
)

type Program

type Program struct {
	Source *Source
	File   *os.File
}

func Compile

func Compile(src []byte) (*Program, error)

Compile will use the Go compiler to compile source code for NAML

func (*Program) Execute

func (p *Program) Execute(flags []string) (*bytes.Buffer, *bytes.Buffer, error)

Execute will execute a compiled NAML program stdout, stderr, err := program.Execute([]string{""})

func (*Program) Remove

func (p *Program) Remove() error

Remove will remove the program from the filesystem

type Source

type Source struct {
	File *os.File
}