> ## 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.
# Packages
> Versioned install definitions that power products, offers, and direct installs
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](/tools/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
```text theme={null}
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](/akua/package-format). For the customer-facing generated form, see [Offers](/marketplace/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.
```python theme={null}
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:
```yaml theme={null}
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](/networking/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](/networking/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](/packages/repositories) | `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.
```bash theme={null}
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.
```bash theme={null}
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.
Create Packages, import published Packages, add versions, and fetch input schemas.
Register an OCI-backed Package and its first immutable version.
Add another immutable version to an existing OCI-backed Package.
Wrap a Package into a sellable product.
Create private or reusable sales paths for a Product or Package version.
Run a Package version as a direct installation.
## Related topics
Turn a Package into a sellable catalog item.
Author `package.k`, `Input`, and `@ui` annotations.
Follow authored source into an immutable Package version.
See how a Package version materializes for each install.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.