Concepts

Documentation Index

Fetch the complete documentation index at: https://akua-1dce587a.mintlify.app/llms.txt

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

Akua turns your application into per-customer deployments through a small set of primitives. This page lays them out so you can predict what happens at each stage, across any surface: dashboard, CLI, API, or git.

​

The flow at a glance

A Package is the deploy definition. You can author one directly, or attach Sources to supply its dependencies (GitHub repos add automatic image builds; Helm and Docker sources point at upstream content). Products wrap a Package with pricing for sale; Direct installs use a Package internally. When a customer installs, Akua materializes the Package into a per-installation git repository — the customer’s specific copy, with their inputs and rendered manifests.

​

The primitives

​

Package

The deploy definition, and the canonical primitive. A Package describes how to turn customer inputs and upstream dependencies into Kubernetes resources. It contains:

• akua.toml: package metadata and a list of upstream dependencies (Helm charts, container images, other Packages)
• package.k: composition logic in KCL that turns inputs into resources; can import declared dependencies and patch any field on rendered output
• An input schema: what customers can configure

A Package is portable on its own. Akua doesn’t need to know where the dependencies originally came from to render and deploy it. The akua.toml is the contract.

​

Source

An upstream connection that supplies content to a Package. What the version represents depends on the source type:

• GitHub repository: Railpack builds a container image on every push. The Package exposes an input field for the image tag, so picking up a fresh build is an input change.
• Helm chart: A reference to a chart on Artifact Hub, an OCI registry, or git. The Package’s akua.toml pins which chart version to vendor; bumping the chart is a Package-version change.
• Docker image: A reference to a public container image. The Package exposes an input field for the tag, so changing the tag is an input change (no Package re-version needed).

Sources are wiring, not content. The deploy definition lives in the Package’s akua.toml and package.k; Sources are how the upstream content gets attached. The simple flow is: pick sources → Akua composes a Package → ship it. Or skip Sources entirely and author the Package yourself.

​

Product

A sellable wrapper around a Package: pricing, marketplace metadata, and any product-level default inputs. Products appear in the marketplace once pricing is configured. Use a Product when you want to sell software. For internal tools, use a Direct install instead.

​

Direct install

A deployment that uses a Package without product wrapping. No pricing, not listed in the marketplace. Same Package, just used internally.

​

Installation

A specific running deployment in a workspace. Two flavors:

• Product-based installation: created when a customer purchases a Product; inherits the Product’s defaults and supports per-install overrides on top.
• Standalone installation: created directly without a Product; owns its inputs 1:1.

Both flavors materialize the Package into a per-install repository.

​

Per-install repository

The materialized Package for one installation: a private git repository owned by the customer’s workspace. The wizard, the CLI, and git push all edit the same repository. Re-rendering is pure: identical inputs always produce identical manifests, so equivalent edits don’t churn deploys. See Installation repositories → for the full model.

​

How updates flow to customers

An update is any change to a Package: its inputs, its package.k composition, or its akua.toml pinned dependencies. The change might come from the seller editing a Product, the customer editing their install’s inputs, or an automated bump (a fresh GitHub-built image landing as a new tag, or a new Helm chart version pinned in akua.toml). All of them are Package-level edits. Once a Package change happens, Akua propagates it:

1. Per-install re-render: each affected installation gets a fresh render of the new Package against its own inputs.yaml, written to its own repository.
2. Customer overrides preserved: install-specific overrides on top of product defaults survive the re-render; only what changed in the Package flows through.
3. Independent rollout: each install advances on its own commit history; a failed render on one customer’s install doesn’t block the others.
4. Pinning respected: if an install is pinned to an older Package version, the bump skips it until the customer (or seller) chooses to upgrade.

To the seller, updating customers is a single decision: edit the product’s defaults or composition and ship the new Package version. To the platform, it’s a fan-out. Every installation re-renders and converges on its own schedule.

​

What builds on what

Customer A and Customer B can install the same Product and get isolated repositories with different inputs, different version pinning, and independent deploy histories. A change you make for Customer A stays scoped to their repository.

​

Customization surfaces

Three surfaces edit the same state:

• Dashboard wizard: a form view over the Package’s input schema, generated from the Input schema and any @ui annotations the author added
• CLI / API: programmatic access to the same inputs
• git push: direct edits to the installation’s repository

The wizard writes to inputs.yaml. A git push to that file is equivalent. Akua re-renders on every change. For edits the wizard doesn’t expose (patching individual fields, adding sidecars, swapping image registries), see Customize an installation via git →. Sellers control the wizard’s presentation by writing docstrings and @ui annotations on their Input schema. The same schema drives shareable install links at /i/<slug>.

​

Related topics