Packages

Package dependencies composed into a readable Package version card with field, type, and default rows, reused by Product, Offer, and Direct install

A Package is the reusable install definition behind an Akua install. It owns the composition logic, dependencies, version history, and input schema that the dashboard, API, and offer wizard use. Products and Offers build on Packages. A Product is the sellable wrapper customers discover or buy. An Offer is the shareable sales path for a Product or Package version. The Package is the technical contract both of them point at.

Package first, deployment second

Akua starts from an explicit Package, not from automatic framework detection. Before a Product, Offer, or direct installation can run, the Package must describe what gets rendered, which inputs customers can set, and which cluster capabilities the install needs. This model keeps customer installs repeatable. Each Package version becomes a stable deployment contract that can be installed, audited, and reused across marketplace listings, private Offers, and internal installs. Installations created from that version can roll back through their repository history. If you’re bringing an existing application to Akua, choose the authoring path that matches the source you already have:

Starting point	Best next step
An existing Helm chart	Import or author a Package that depends on the chart and exposes the values customers should edit.
A Docker Compose app	Use the Compose converter to create Kubernetes or Helm starting points, then author the Package contract around the generated resources.
A custom Kubernetes app	Author `package.k` directly and define the customer-facing `Input` schema.
An Akua Package published to OCI	Register the Package with `POST /packages:import` and add immutable versions as you publish them.

Akua does not infer production settings from package.json, a Dockerfile, or a Git branch. Put those choices into the Package, then wrap the Package in a Product or Offer when you’re ready to sell it.

What a Package owns

Surface	Owned by Package
Source	Authored `package.k`, Package metadata, and supported sources such as chart dependencies or container images
Versions	Immutable Package versions with provenance and renderable inputs
Input schema	The customer-facing fields exported from the Package version
Defaults	Safe default inputs used by products, offers, and direct installs
Compatibility	The install shape a workspace must satisfy before using the Package

Packages do not own pricing, customer targeting, payment collection, or marketplace visibility. Those belong to Products and Offers.

Package, Product, Offer

Package version
  Input schema
  Product
    Marketplace listing or Offer
      Order draft
        Installation
  Package Offer
    Order draft
      Installation
  Direct install
    Installation

Use this split when you design your catalog:

Create or import a Package when you need a reusable install definition.
Create a Product when that Package should become a sellable catalog item.
Create an Offer when you want to send a customer a short URL with selected inputs, access rules, and commercial terms.
Use a Direct install when the Package should run internally without Product or Offer wrapping.

Input schemas

Akua exports each Package version’s Input schema to drive generated forms. Docstrings become help text. @ui(...) annotations control grouping, ordering, widget hints, placeholders, and numeric bounds. For authoring details, see Package format. For the customer-facing generated form, see Offers.

The `namespace` and `release_name` inputs

namespace and release_name are reserved. A Package whose Input declares either as a string field receives the installation’s own value there, whatever the field’s default says: its Kubernetes namespace, and a Helm release name unique to that installation. Pass both to every Helm dependency you template.

schema Input:
    namespace: str = "default"
    release_name: str = "release"

_src = nginx.template(nginx.TemplateOpts {
    values = input.values_nginx
    namespace = input.namespace
    release = input.release_name
})

namespace puts the rendered resources where the installation deploys them. release_name keeps them apart from another installation of the same Package: a chart labels its pods app.kubernetes.io/instance: {{ .Release.Name }} and selects on that label from its Service, NetworkPolicy and PodDisruptionBudget. Two installations sharing a release name share those selectors, so each Service resolves to both installations’ pods. Distinct resource names do not separate them, because the selector never mentions the name. Because the installation supplies both values, the generated form offers neither as an editable field, and an Offer cannot pin them. A Package that declares neither input receives its inputs unchanged.

Expose an HTTP service on managed KaaS

Managed KaaS clusters expose Package Services through Akua-managed routing. Don’t set spec.ingressClassName or the kubernetes.io/ingress.class annotation: managed clusters don’t install an in-cluster Ingress controller for Package traffic. Render an HTTPRoute with a hostname, a Service backend, and the routing.akua.dev/output-name annotation instead:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web
  annotations:
    routing.akua.dev/output-name: web
spec:
  hostnames:
    - web-acme.akua.run
  rules:
    - backendRefs:
        - name: web
          port: 80

The annotation identifies the Package output. spec.hostnames defines its public hostname, and backendRefs selects the Service and numeric port that receive traffic. The example uses an Akua-managed preview hostname. Preview domains provide flat *.akua.run hostnames with managed DNS and TLS. To use a domain you control, configure custom-domain routing with Cloudflare Tunnel, then render that hostname in spec.hostnames.

API workflows

Use the Packages API when your automation needs to create or maintain Package records outside the dashboard.

Goal	Endpoint	Result
Create a hosted Package from a Helm chart or authored workspace repository	`POST /packages`	Starts Package creation and returns an operation
Register an already-published OCI-backed Package	`POST /packages:import`	Creates the Package and its first immutable version
Add another version to an existing OCI-backed Package	`POST /packages/{id}/versions`	Creates a new immutable Package version

POST /packages:import and POST /packages/{id}/versions are for Packages that have already been published to an OCI registry. Your workspace must have published Package import access to use either endpoint. The API still requires you to send the version, immutable content reference, and input schema. Akua inspects the published artifact and rejects the request if the artifact metadata doesn’t match the values you send. Public registries work without a saved credential. For private registries, add an active workspace registry credential that matches the registry or repository prefix before you import the Package.

Import a published Package

To import a published Package, your workspace must have published Package import access. Use Akua-Context when your token can access more than one workspace, and send an Idempotency-Key so the request is safe to retry.

curl https://api.akua.dev/v1/packages:import \
  -H "Authorization: Bearer $AKUA_API_TOKEN" \
  -H "Akua-Context: ws_xxx" \
  -H "Idempotency-Key: import-codezero-1-2-3" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "codezero",
    "description": "Codezero Package",
    "oci_ref": "oci://ghcr.io/example/packages/codezero",
    "version": {
      "semver": "1.2.3",
      "ref": "sha256:abc123...",
      "input_schema": {
        "type": "object",
        "properties": {
          "license_key": { "type": "string" }
        }
      }
    }
  }'

The response is the created Package. Store its id; you need it to add future versions, create Products, create Offers, or install the Package directly. If you retry with the same Idempotency-Key and the same body, Akua returns the same imported Package. If you reuse the key with different Package or version data, Akua returns a conflict so your automation doesn’t accidentally point one retry key at two different artifacts.

Add versions to an imported Package

After an OCI-backed Package exists, add later published versions with POST /packages/{id}/versions. This endpoint uses the same published Package import access as the initial import.

curl https://api.akua.dev/v1/packages/pkg_xxx/versions \
  -H "Authorization: Bearer $AKUA_API_TOKEN" \
  -H "Akua-Context: ws_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "semver": "1.2.4",
    "ref": "sha256:def456...",
    "input_schema": {
      "type": "object",
      "properties": {
        "license_key": { "type": "string" }
      }
    }
  }'

Direct version creation only applies to OCI-backed Packages. You still provide the immutable content reference and input_schema for each version, and Akua verifies both values against the published artifact before registering the version. Hosted Packages created through POST /packages publish versions through their Package creation flow.

API

Manage Packages programmatically from the generated API reference. To run a Package without wrapping it in a Product, create a direct installation from the Installs API.

Packages API

Create Packages, import published Packages, add versions, and fetch input schemas.

Import a published Package

Create a Package version

Add another immutable version to an existing OCI-backed Package.

Products API

Wrap a Package into a sellable product.

Offers API

Create private or reusable sales paths for a Product or Package version.

Installs API

Run a Package version as a direct installation.

Products

Turn a Package into a sellable catalog item.

Package format

Author package.k, Input, and @ui annotations.

Package repositories

Follow authored source into an immutable Package version.

Installation repositories

See how a Package version materializes for each install.

Installations

Package authoring

Repository delivery

Automation

Package first, deployment second

What a Package owns

Package, Product, Offer

Input schemas

The `namespace` and `release_name` inputs

Expose an HTTP service on managed KaaS

API workflows

Import a published Package

Add versions to an imported Package

API

Packages API

Import a published Package

Create a Package version

Products API

Offers API

Installs API

Products

Package format

Package repositories

Installation repositories

​Package first, deployment second

​What a Package owns

​Package, Product, Offer

​Input schemas

​The namespace and release_name inputs

​Expose an HTTP service on managed KaaS

​API workflows

​Import a published Package

​Add versions to an imported Package

​API

Packages API

Import a published Package

Create a Package version

Products API

Offers API

Installs API

​Related topics

Products

Package format

Package repositories

Installation repositories

Package first, deployment second

What a Package owns

Package, Product, Offer

Input schemas

The `namespace` and `release_name` inputs

Expose an HTTP service on managed KaaS

API workflows

Import a published Package

Add versions to an imported Package

API

Related topics