Installation lifecycle

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.

An installation is a living resource, not a one-shot deploy. Once you create one, Akua keeps it converging toward the state in its repository and exposes that work as something you can observe: a current state, a render history, the pods running on your cluster, and a live log stream. This page covers that lifecycle end to end. “Installation” is the unit. It is distinct from a Kubernetes Deployment, which is one of the resource kinds an installation might render. The wire ID is inst_… and the API tag is Installs.

​

The lifecycle states

Every installation reports a single lifecycle state. It moves through the states below as Akua renders the package, syncs the result to your cluster, and watches the running resources.

• pending: the installation exists; work has not started yet.
• rendering: Akua is turning the package and its inputs into Kubernetes manifests.
• syncing: the rendered manifests are being applied to your cluster.
• healthy: every resource reports healthy and the cluster matches the repository.
• degraded: the installation is live but one or more resources are unhealthy or still settling.
• failed: a render or sync could not complete. The status carries the reason.
• deleted: the installation has been torn down.

A healthy installation is not frozen. When inputs change or upstream resources drift, it re-renders and re-syncs, passing back through rendering and syncing before returning to healthy. A status flag tells you when this reconciliation is in flight.

​

Create an installation

You create an installation in one of two ways, both covered on the Installations overview: a product-based install (from a marketplace purchase, an Offer, or a manual product install) or a direct install (an application you run without a Product). Both resolve to the same resource and the same lifecycle. Creating an installation provisions its repository, records the chosen package version and any initial inputs, and starts the first render. From there it follows the states above on its own; you do not drive each step by hand.

​

Renders and render history

A render is one attempt to turn the installation’s package, inputs, and vendored upstream into the manifests your cluster applies. Renders are the audit trail of how the installation reached its current shape.

• Akua renders automatically whenever the inputs or composition change.
• You can also request a render explicitly, for example to retry after fixing a failed input or to attach a message to the attempt.
• Renders are content-addressed. If a render produces manifests identical to the last one, Akua records no new revision and triggers no rollout, so equivalent edits never churn your cluster.

Each render is kept as an artifact with its own ID, so the render history lets you see what was produced, when, and whether it changed the installation. This is the same content-hashing model described in package versioning, viewed from the render side rather than the commit side.

​

Read the status

The installation status is the single place to answer “is this install healthy right now.” It reports:

• Health: whether the running resources are healthy, degraded, or still progressing.
• Sync: whether the cluster matches the repository or has pending changes to apply.
• Revision: the deployed revision the cluster is currently converged to.
• Per-resource health: the kind, name, and health of each rendered resource, so you can find the one workload holding the install in degraded.
• Reconciling: whether a render or sync is in flight, so a transient degraded is not mistaken for a stuck one.

Use the status for dashboards and automated health checks. It is the read model behind the state badge in the dashboard.

​

Inspect pods and stream logs

When you need to look past the rolled-up status into the running workload, two surfaces drop you to the pod level:

• Pods: the current pod names and their containers for the installation. This is how you find which pod to inspect when a resource reports unhealthy.
• Logs: a live log stream for the installation. Stream all pods at once, or pass a single pod name to follow just that one. This is the fastest path from “the install is degraded” to the line that explains why.

Both read directly from the cluster the installation runs on, so they reflect the live workload rather than the last render.

​

Delete an installation

Deleting an installation tears down the resources it created on your cluster and moves the installation to deleted. The teardown runs in the background and is safe to retry: a repeated delete on an installation already being removed converges on the same end state rather than erroring. Deletion is scoped to the one installation. Other installations of the same product, each with its own repository and lifecycle, are untouched.

​

API

Drive the full lifecycle over the REST API. Per-endpoint parameters, response shapes, and a try-it playground live in the auto-generated reference.

​

Related topics