lingon

README

Lingon 🍒 - Libraries for building platforms with Go

• What is this?
  • It can do 4 things so far
• Who is this for?
• Project status
• Required knowledge
• Getting started
• Examples
• Install binaries
  • Github releases
  • Install from source
• Motivation
• Extraordinary use cases
• Why Go?
• Similar projects
• License

What is this?

Write Terraform (HCL) and Kubernetes (YAML) in Go. see Rationale for more details.

Lingon is not a platform, it is a thin wrapper around terraform and kubernetes API in a library meant to be consumed in a Go application that platform engineers write to manage their platforms. It is a tool to build and automate the creation and the management of platforms regardless of the target infrastructure and services.

It can do 4 things so far

• import kubernetes YAML manifests to valid Go code (even CRDs) kube.Import
• export Go code to kubernetes YAML manifests kube.Export
• generate Go code from Terraform providers terragen.GenerateProviderSchema and terragen.GenerateGoCode
• export terraform Go code to valid Terraform HCL terra.Export

The only dependencies you need are:

• Go
• Terraform CLI
• kubectl

Who is this for?

Lingon is aimed at advanced platform teams who need to automate the lifecycle of their cloud infrastructure and have suffered the pain of configuration languages and complexity of gluing tools together with more tools.

Project status

This project is in beta. The APIs are stable, but we do not promise backward compatibility at this point. We will eventually promise backward compatibility when the project is more battle tested.

This was a proof-of-concept at volvo-cars. Unfortunately the project for which Lingon was being developed ended. The original authors (jacob and julien) believe in the concept and are now maintainers of this project and will make sure it is healthy and receives updates.

See FAQ for more details.

Required knowledge

This is not a tutorial on how to use Go, Terraform or Kubernetes. Lingon doesn't try to hide the complexity of these technologies, it embraces it.

Which is why you need to know how to use these technologies to use Lingon.

• Go
• Terraform
• Kubernetes

Getting started

Note that in the terraform case, the code generation is fast. Compiling all the generated resources will take a while. Thankfully, Go is fast at compiling and keeps a cache of compiled packages. Expect to wait a few minutes the first time you run go build after generating the code.

• Terraform
• Kubernetes

Examples

• All the Examples are in the documentation.
• Convert kubernetes manifests from YAML containing CRDs to Go: example_import_test.go
• Export Go code to kubernetes manifests: kube_test.go
• Create the HCL code for Terraform: aws_test.go
• An example is Platypus which shows how the kubernetes and terraform libraries can be used together.

Install binaries

Lingon provides helper binaries.

• explode - explode a kubernetes manifests YAML file into multiple files organized by kind and namespace.
• kygo - convert kubernetes YAML manifests to Go code
• terragen - generate Go code from Terraform providers

Github releases

Or simply download the binaries from the releases page.

Install from source

go install github.com/golingon/lingon/cmd/explode@latest
go install github.com/golingon/lingon/cmd/kygo@latest
go install github.com/golingon/lingon/cmd/terragen@latest

Motivation

See Rationale for more details.

Extraordinary use cases

Lingon might be helpful if you need to:

• use the SDK of your cloud provider to access APIs (alpha, beta, deprecated) not included in a Terraform provider.
• authenticate to a multitude of providers or webhook with specific requirements (e.g. Azure SSO, AWS, Github, Slack, etc.)
• automate some parts of the infrastructure that are really hard to test (e.g. iptables, DNS, IAM, etc.)
• store the state of the infrastructure in a database for further analysis
• collect advanced metrics about the failures occurring during the deployment of the infrastructure
• enforce advanced rules on kubernetes manifests before deploying it (e.g. every service account must be related to a role and that role cannot have '*' in access rights, etc.)
• define CI/CD pipelines as imperative code, not declarative.
• execute smoke tests after deploying changes to the platform (HTTP, gRPC, DB connection, etc.)
• write unit tests for your infrastructure

Why Go?

See Why Go for more details.

Similar projects

See Comparison for more details.

License

This code is released under the Apache-2.0 License.

Documentation

Overview

Lingon is a collection of libraries and tools for building platforms using Go.

The following technologies are currently supported:

• Terraform
• Kubernetes

The only dependencies you need are:

• Go
• Terraform CLI
• kubectl

The packages currently available are:

Kube

• [kube.App] struct that is embedded to mark kubernetes applications

• [kube.Export] converts kubernetes objects defined as Go struct to kubernetes manifests in YAML. - [kube.Explode] kubernetes manifests in YAML to multiple files, organized by namespace.

• [kube.Import] converts kubernetes manifests in YAML to Go structs.

Kubeconfig

utility package to read and merge kubeconfig files without any dependencies on `go-client`.

Kubeutil

Reusable functions used to create and validate kubernetes objects in Go.

Terra

Core functionality for working with Terraform.

• [terra.Export] converts a [terra.Stack] to HCL files.

Terragen

Generate Go code for Terraform providers. - [terragen.GenerateProviderSchema] generates a terraform provider JSON schema from terraform provider registry. - [terragen.GenerateGoCode] converts a terraform provider schema to Go structs.

Testutils

Reusable test functions.

[kube.Export]: https://pkg.go.dev/github.com/golingon/lingon/pkg/kube#Export [kube.Explode]: https://pkg.go.dev/github.com/golingon/lingon/pkg/kube#Explode [kube.Import]: https://pkg.go.dev/github.com/golingon/lingon/pkg/kube#Import [kube.App]: https://pkg.go.dev/github.com/golingon/lingon/pkg/kube#App [terra.Export]: https://pkg.go.dev/github.com/golingon/lingon/pkg/terra#Export [terragen.GenerateProviderSchema]: https://pkg.go.dev/github.com/golingon/lingon/pkg/terragen#GenerateProviderSchema [terragen.GenerateGoCode]: https://pkg.go.dev/github.com/golingon/lingon/pkg/terragen#GenerateGoCode