Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.akua.dev/llms.txt

Use this file to discover all available pages before exploring further.

Every installation on Akua lives in its own private git repository. The repository is the source of truth for the deployment: your customer’s wizard inputs, the composition logic that turns those inputs into Kubernetes resources, and the rendered manifests your cluster actually applies. Editing the repository is what changes a deployment (through the dashboard, the API, or git push). This page explains the model. For the step-by-step “how to clone and edit” walkthrough, see Customize an installation via git.

​
Why per-installation

A product on Akua can have hundreds of installations. Each one belongs to a different customer, runs in a different cluster, may pin to a different upstream version, and may carry its own ad-hoc tweaks. The per-installation repository keeps these isolated:
  • Customer A can edit their installation’s inputs.yaml without touching anyone else’s deployment.
  • A patch you make for Customer B stays scoped to their repository.
  • Each installation’s deployment history is a normal git log (branchable, diffable, revertible), independent of every other install.
The alternative (one shared repository, many directories) would make customer isolation a feature you’d have to enforce. With separate repositories, isolation is the default.

​
What’s in the repository

your-install-id/
├── akua.toml          # Package metadata: name, version, dependencies
├── package.k          # Composition logic — turns inputs into resources
├── inputs.yaml        # The wizard values your customer set
├── upstream/          # Pinned vendored copy of the source package
└── manifests/         # Rendered Kubernetes resources (Akua applies these to your cluster)
File or directoryOwnerPurpose
akua.tomlYouPackage identity. Mostly stable; edited when bumping the upstream pin.
package.kYouThe composition layer. Adds install-scoped labels, can patch any field on any rendered resource, can append extra resources the upstream doesn’t include.
inputs.yamlCustomer + youThe wizard’s output. Editable from the dashboard wizard, the API, or directly via git.
upstream/AkuaA pinned snapshot of the product’s source. Vendored at provision time so renders are deterministic and offline-capable.
manifests/Akua (rendered)Output of package.k + inputs.yaml against upstream/. Regenerated on every change; never edit manually.

​
How it stays in sync with the dashboard

The repository and the dashboard are not two separate stores. They are two views over the same content. The dashboard wizard reads inputs.yaml; saving a wizard change writes a commit. A direct git push to inputs.yaml shows up in the dashboard immediately. A git revert rolls the dashboard view back too. This means you can mix the two surfaces freely:
  • A customer changes a value through the wizard → commit lands → you see it in git log.
  • You push a fix to package.k from the CLI → next dashboard load reflects it.
  • An automation script edits inputs.yaml over the API → equivalent to editing in the wizard.
The dashboard wins conflicts on inputs.yaml: if a customer saves a wizard change while you’re editing locally, the dashboard write happens first and your local push will fast-forward or fail. Use package.k for changes that must survive customer-driven wizard updates.

​
Rendering: pure, idempotent, offline

The render step turns package.k + inputs.yaml + upstream/ into manifests/. It has three properties worth understanding:
  1. Pure. Identical inputs always produce identical manifests, byte-for-byte. There’s no clock, no network, no secret material in the render context.
  2. Idempotent. Akua hashes the rendered manifests; if a render produces the same hash as the previous one, no commit is made and no deploy is triggered. Whitespace edits to inputs.yaml don’t churn deploys.
  3. Offline-capable. Because upstream/ is vendored, renders work without any external fetches. If the original source package becomes unavailable, your installations keep working.
Together these mean: re-running a render against the same commit always produces a no-op, and the deployment your cluster syncs to is fully reproducible from the repository alone.

​
Where the repository lives

Akua-managed installations are hosted at git.akua.dev/<your-org>/<install-id>.git. Repositories are private and isolated to your workspace. Authenticate with your dashboard token (use any string for the username; the token is the password). The dashboard’s Source tab on every installation shows the clone URL, the latest deployed commit SHA, and a link into the repository’s history.

​
Repositories and the wider package model

The per-installation repository is one slice of Akua’s package model. The same package.k + inputs concept applies to:
  • Products (today): the source you publish gets vendored into every installation.
  • Policies (planned): workspace-wide policy bundles that layer on top of per-install renders.
  • Repository change requests: agent-authored or human-authored forks of an installation’s repo, reviewed and accepted through Akua rather than landed directly. See AI agents working with repositories.
The repository as a primitive (versioned, isolated, pure to render) is what makes those follow-on capabilities composable.

Customize an installation via git

Edit inputs, patch resources, push commits.

Package generation

How Akua generates packages from your sources.

Package versioning

How commit history maps to deployments and how to roll back.

Repositories API

Endpoints, parameters, and try-it playground.