Getting Started

This section walks you through everything needed to get Tazuna running on your local machine for the first time. Once you have completed it, see Guides - Writing Your First tazuna.yaml for how to actually write a tazuna.yaml.

Goals:

The tazuna binary is installed on your machine
tazuna version runs successfully
You understand which clusters and external tools are required

1. Installation

tazuna is a single binary. Install it via one of the following methods.

Use a Release Binary

Download the archive for your OS / arch from GitHub Releases, and place tazuna somewhere on your PATH.

# Example (after extracting the macOS arm64 / Linux amd64 archive)
mv tazuna /usr/local/bin/
tazuna version

This is the recommended method when you want to pin a specific version in CI or guarantee reproducibility.

Use `go install`

If you have a Go 1.x toolchain, you can build directly from source.

go install github.com/pepabo/tazuna@latest

You can pin a version with @v0.x.y instead of @latest. The binary is placed in $(go env GOBIN) (or $(go env GOPATH)/bin if unset).

Build Directly From Source

If you want to build it yourself from a cloned repository, do the following.

make build      # ./tazuna is generated
make install    # Install into /usr/local/bin (uses sudo)

2. Verify the Installation

After installation, verify that the following command works without any configuration.

tazuna version
tazuna --help

The output of tazuna version looks like the following (actual values vary by environment).

tazuna v0.1.0 (commit abc1234, built 2026-05-25T03:21:00Z, darwin/arm64)

For local builds, version / commit / built will be dev / none / unknown respectively (see tazuna version).

3. Prepare the Prerequisites

For tazuna to operate against a cluster, a few prerequisites are needed. Not all of them are required. You only need to prepare the ones marked “Required” in the table below first; 1Password / git can be set up optionally depending on the features you use.

Dependency	Required?	Description
Kubernetes cluster	Yes (when using `apply` / `destroy` / `state ...`)	Setting up the control plane is outside Tazuna’s scope. For local experiments, use KinD / minikube; for remote, EKS / GKE / AKS / `kubeadm` and so on are all fine.
`kubeconfig` current-context	Yes (same as above)	Verify with `kubectl config current-context` that it points to the cluster you want to apply to. Make sure `kubectl get nodes` works.
`kubectl`	- (recommended)	Tazuna itself does not use it, but you will use it for `kubeconfig` manipulation and to verify applied results.
`kustomize` / `helmfile` / `helm` binaries	- (not needed)	Tazuna embeds them as Go libraries, so installing external binaries is not required.
1Password CLI (`op`)	- (only when using `type: genesissecret` or helmfile.vars’s `from: op`)	Requires the `op` command to be on `PATH` and authenticated with a service account.
`git`	- (optional)	Used to fill in `_metadata.gitCommitHash` during `tazuna state sync`. If run outside a repository or if `git` is not installed, an empty string is recorded without raising an error.

Cluster selection and kubeconfig handling are also discussed in the guide’s Prerequisites section.

4. Next Steps

At this point tazuna is running on your machine.

Proceed to Guides - Writing Your First tazuna.yaml, where you will write an actual tazuna.yaml and run apply.
When you just want to look up the specification, see the Reference.
If you want to understand “why it is shaped this way,” see Concepts.

Keyboard shortcuts

Tazuna