Concepts

Akua turns your application into per-customer installs 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 versioned install contract. You can author one directly, then declare supported dependencies such as Helm charts, container images, or other Packages. Products wrap a Package for sale; Offers carry the concrete customer path, terms, access rules, and short URL. 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 versioned install contract, and the canonical primitive. A Package describes how to turn customer inputs and upstream dependencies into Kubernetes resources for an installation. 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.

​

Dependencies

Upstream content that a Package vendors or references. What the version represents depends on the dependency type:

• 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.
• Container image: A reference to an OCI image used by the Package’s Kubernetes resources. Changing the tag is an input or Package-version change, depending on how the Package author exposes it.
• Package: A reusable dependency imported by another Package.

Dependencies are wiring, not the install contract. The install contract lives in the Package’s akua.toml and package.k; dependencies are the upstream content the Package renders from. The simple flow is: author a Package, declare dependencies, then ship it.

​

Product

A sellable wrapper around a Package: marketplace metadata, selected Package version, and default inputs. Products can appear in the marketplace or stay private behind Offers. Use a Product when you want to sell software. For internal tools, use a Direct install instead.

​

Offer

A customer-facing sales path for a Product or Package version. An Offer owns the short URL, access rules, pre-filled field values, expiry, and commercial terms for a specific customer or reusable link. Use an Offer when you want to send a customer directly into the generated install wizard.

​

Direct install

An installation that uses a Package version without Product wrapping. No pricing, not listed in the marketplace. Same Package model, just used internally.

​

Installation

A specific running installation in a workspace. Two flavors:

• Product-based installation: created when a customer purchases a Product; inherits the selected Package version’s defaults and supports per-install overrides on top.
• Direct installation: created directly without a Product; selects a Package version and 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 accepted repository changes all edit the same repository. Re-rendering is pure: identical inputs always produce identical manifests, so equivalent edits don’t churn installs. See Installation repositories → for the full model.

​

How updates flow to customers

An update reaches an installation when you select a new Package version or accept a repository change request against that installation. Package versions are immutable release units: creating one doesn’t change existing installations by itself. Once you choose a rollout path, Akua updates each installation independently:

1. Version selected: the Product, Offer, direct install, or repository change request points at the Package version that should run.
2. Per-install re-render: each affected installation gets a fresh render of that Package version against its own inputs.yaml, written to its own repository.
3. Customer overrides preserved: install-specific overrides on top of Package version defaults survive the re-render.
4. Independent rollout: each install advances on its own commit history; a failed render on one customer’s install doesn’t block the others.

To the seller, updating customers is a deliberate release decision: publish the Package version, then choose which installations should move to it. Every selected 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 selected Package versions, 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
• Repository change requests: reviewed edits to the installation’s repository

The wizard writes to inputs.yaml. Accepted repository changes update the same install state, and Akua re-renders after each accepted 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 Offers at /i/<hash>.

​

Related topics