README
¶
Unobin
Unobin means one binary. It's a tool for infrastructure automation inspired by Terraform, Ansible, and others, but unlike those, unobin compiles your code to a standalone binary called a factory.
Quickstart
Install unobin:
go install github.com/cloudboss/unobin/cmd/unobin@latest
To start a new factory, use the unobin generate factory command.
unobin generate factory -o appdeploy
Now you will have a new directory appdeploy (given by -o) containing a main.ub file. Edit main.ub to import libraries and add resources.
When you compile, give it a library path with --library-path. This is similar to Go's module-path when running go mod init. It will normally be the git repo where your library will live.
In the appdeploy directory, run:
unobin compile -o ./appdeploy-compiled --build --library-path github.com/cloudboss/mystack
Now there will be an executable called ./appdeploy-compiled/appdeploy. You can use it to generate a configuration file from the stack's input schema:
./appdeploy-compiled/appdeploy schema template -o config.ub
Edit the generated config.ub if necessary.
Then run plan and apply. A factory cannot apply without first planning.
./appdeploy-compiled/appdeploy plan -o plan.json -c config.ub
./appdeploy-compiled/appdeploy apply plan.json
See the examples directory for various example stacks that you can compile and run.
Benefits of Unobin
No Dependencies
An unobin factory includes the runtime and dependencies. It's like having your modules, providers, and Terraform itself all included in one executable.
Consistent Interface
All factories have the same command line arguments with automatically generated help. If you know how to run one, you know how to run all of them.
Reproducible
The goal is: if it works on my machine, then it works on your machine. You don't need to do extra steps or install anything before you can deploy your infrastructure. Just download the factory and run it.
Input Validation
All factories validate their inputs against a schema and will not run if the inputs do not pass validation.
Comparison with Other Tools
| Unobin | Ansible | Chef | Terraform | |
|---|---|---|---|---|
| No server | ✓ | ✓ | ||
| Local mode | ✓ | optional | ✓ | ✓ |
| Syntax | Unobin | YAML+Jinja2 | Ruby | HCL |
| Works on my machine | ✓ | maybe | maybe | maybe |
| Works on your machine | ✓ | maybe | maybe | maybe |
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
hack
command
Command hack is the build-time developer tooling for the unobin repo: tasks that run from a source checkout, not features of the shipped unobin binary.
|
Command hack is the build-time developer tooling for the unobin repo: tasks that run from a source checkout, not features of the shipped unobin binary. |
|
unobin
command
|
|
|
examples
|
|
|
configurations/greet
Package greet is a small demonstration library that exists so examples and tests can exercise configuration routing.
|
Package greet is a small demonstration library that exists so examples and tests can exercise configuration routing. |
|
constraints/deploy
Package deploy is a small demonstration library that exists so examples and tests can exercise Go-declared constraints.
|
Package deploy is a small demonstration library that exists so examples and tests can exercise Go-declared constraints. |
|
pkg
|
|
|
backends
Package backends holds the fixed set of state backends and encrypters a factory can use.
|
Package backends holds the fixed set of state backends and encrypters a factory can use. |
|
check
Package check runs the compile-time checks over a parsed stack: reference and type resolution, literal constraint evaluation, and @for-each nesting.
|
Package check runs the compile-time checks over a parsed stack: reference and type resolution, literal constraint evaluation, and @for-each nesting. |
|
codegen
Package codegen generates Go source from a resolved AST.
|
Package codegen generates Go source from a resolved AST. |
|
compile
Package compile turns factory source into a buildable Go module: it parses and validates the stack, resolves its imports, reads each Go library's schema, runs the compile-time checks, generates main.go and one package per UB library, and optionally runs `go build`.
|
Package compile turns factory source into a buildable Go module: it parses and validates the stack, resolves its imports, reads each Go library's schema, runs the compile-time checks, generates main.go and one package per UB library, and optionally runs `go build`. |
|
constraint
Package constraint lets a Go library type declare cross-field constraints on its inputs in a type-safe, string-free way.
|
Package constraint lets a Go library type declare cross-field constraints on its inputs in a type-safe, string-free way. |
|
defaults
Package defaults lets a Go library type declare schema defaults for its inputs in a type-safe, string-free way.
|
Package defaults lets a Go library type declare schema defaults for its inputs in a type-safe, string-free way. |
|
deps
Package deps models a factory's dependencies.
|
Package deps models a factory's dependencies. |
|
docgen
Package docgen renders unobin reference documentation as Markdown for the docs site.
|
Package docgen renders unobin reference documentation as Markdown for the docs site. |
|
encoding/ub
Package ub encodes Go values as unobin language literals, the counterpart to encoding/json for unobin's own syntax.
|
Package ub encodes Go values as unobin language literals, the counterpart to encoding/json for unobin's own syntax. |
|
envencrypt
Package envencrypt holds unobin's built-in encrypters.
|
Package envencrypt holds unobin's built-in encrypters. |
|
fs
Package fs holds filesystem helpers shared across packages.
|
Package fs holds filesystem helpers shared across packages. |
|
git
Package git wraps the go-git operations the resolver needs: resolving a ref to a commit SHA without fetching, listing a repo's tags, and cloning a repo at a specific ref into a directory.
|
Package git wraps the go-git operations the resolver needs: resolving a ref to a commit SHA without fetching, listing a repo's tags, and cloning a repo at a specific ref into a directory. |
|
gogen
Package gogen generates Go library source code from external schema formats (CFN registry schemas, TF provider schemas, DCL YAML).
|
Package gogen generates Go library source code from external schema formats (CFN registry schemas, TF provider schemas, DCL YAML). |
|
gogen/tf
Package tf parses Terraform provider schemas (from "terraform providers schema -json") and converts them to gogen.ResourceSchema values for Go code generation.
|
Package tf parses Terraform provider schemas (from "terraform providers schema -json") and converts them to gogen.ResourceSchema values for Go code generation. |
|
goschema
Package goschema reads a Go library's source to learn the output schema of each registered resource, data source, and action.
|
Package goschema reads a Go library's source to learn the output schema of each registered resource, data source, and action. |
|
graphprint
Package graphprint renders a runtime DAG as either a plain indented listing or a Graphviz DOT document.
|
Package graphprint renders a runtime DAG as either a plain indented listing or a Graphviz DOT document. |
|
lang
Package lang holds the unobin source language: PEG grammar, lexer, AST.
|
Package lang holds the unobin source language: PEG grammar, lexer, AST. |
|
localstate
Package state holds unobin's local state backend and the built-in encrypters.
|
Package state holds unobin's local state backend and the built-in encrypters. |
|
resolve
Package resolve handles import resolution and lock file management.
|
Package resolve handles import resolution and lock file management. |
|
runner
Package runner is the CLI scaffolding every compiled factory binary links into.
|
Package runner is the CLI scaffolding every compiled factory binary links into. |
|
runtime
Package runtime is the execution engine linked into every compiled factory binary.
|
Package runtime is the execution engine linked into every compiled factory binary. |
|
sdk/cfg
Package cfg is the typed vocabulary a Go library uses to declare its configuration.
|
Package cfg is the typed vocabulary a Go library uses to declare its configuration. |
|
sdk/cfg/validate
Package validate provides standard Validator constructors for cfg configuration fields.
|
Package validate provides standard Validator constructors for cfg configuration fields. |
|
sdk/encrypt
Package encrypt defines the contract a state-file encrypter implements.
|
Package encrypt defines the contract a state-file encrypter implements. |
|
sdk/state
Package state defines the contract a state backend implements.
|
Package state defines the contract a state backend implements. |
|
toolchain
Package toolchain pins the external tools `unobin compile` shells out to and fetches them through a shared cache, so builds use the same versions across machines regardless of what is on ${PATH}.
|
Package toolchain pins the external tools `unobin compile` shells out to and fetches them through a shared cache, so builds use the same versions across machines regardless of what is on ${PATH}. |
|
typecheck
Package typecheck holds unobin's semantic type model and the static type checker that runs after parsing.
|
Package typecheck holds unobin's semantic type model and the static type checker that runs after parsing. |
|
ubtest
Package ubtest runs file-based tests for .ub source fixtures.
|
Package ubtest runs file-based tests for .ub source fixtures. |
Click to show internal directories.
Click to hide internal directories.