> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/reference/release-lifecycle.md).

# Release lifecycle

Kangal releases are customer-consumable product versions. Release notes are the source of truth for supported upgrade paths, compatibility changes, required preparation, known limitations, deprecations, and rollback boundaries for each version.

## Versioning

Kangal product versions use `MAJOR.MINOR.PATCH` semantics:

* `PATCH` fixes defects or security issues without intentionally changing supported public contracts.
* `MINOR` adds backward-compatible capabilities and can deprecate existing behavior.
* `MAJOR` can introduce breaking API, configuration, deployment, or data changes.
* A suffix such as `-rc.1` identifies a pre-release. Do not use a pre-release in production unless its release notes and your support agreement explicitly allow it.

The Helm chart has its own version because chart templates, values, and dependencies can change independently from application code. Pin both the Kangal product version and chart version listed in the release notes. Do not deploy a moving version such as `latest` in a shared or production environment.

## Compatibility contract

* New integrations should use the versioned Admin API under `/api/v1/admin/...` and generate clients from the OpenAPI document served by the deployed environment.
* Additive response fields can appear in patch and minor releases. Clients must ignore unknown fields and must not depend on object field order.
* A documented deprecation period precedes removal of a supported public endpoint, field, configuration key, or CLI command unless an urgent security issue requires a shorter path.
* API, frontend, workers, and data-plane components should run the same product version. Mixed versions are supported only during an upgrade window or when release notes explicitly state otherwise.
* Use `kangalctl` from the exact source release that matches the server. The shared `/api/v1` prefix alone does not guarantee cross-release CLI compatibility.
* Helm values, configuration bundles, plugins, providers, and database changes are compatible only as stated in the target release notes and migration guidance.

## Before upgrading

1. Read every release note from the installed version through the target version. Confirm that the proposed path is supported and identify required intermediate releases.
2. Record the current product version, chart version, enabled components, plugins, provider integrations, data-plane versions, and environment-specific values.
3. Review API, CLI, configuration, plugin, provider, operating-system, Python, database, Redis, and Kubernetes requirements that apply to the target release.
4. Take the backups and configuration snapshots required by the release notes. Verify that restore credentials, retention, and a recent restore test are available.
5. Export the current Kangal configuration and store it as protected change evidence; remember that redacted exports are not secret backups.
6. Rehearse the upgrade in a representative non-production environment with production scale, protocols, plugins, and integrations that matter to the deployment.
7. Define the maintenance window, traffic plan, acceptance checks, stop conditions, rollback owner, and the latest point at which rollback remains data-compatible.

## Verify the release

Before installation, obtain the release artifacts through the approved distribution channel and follow the integrity-verification instructions supplied with that release. Confirm that the product version, chart version, release notes, and expected component versions agree.

In the rehearsal and production window, verify at least:

* rendered configuration and value changes before applying them;
* database and configuration migration previews where provided;
* workload readiness through `/health` and `/ready`;
* administrator login, tenant isolation, and required Admin API operations;
* representative gateway routes, authentication, rate limits, plugins, upstreams, TLS, and any WebSocket, gRPC, TCP, streaming, or AI paths in use;
* background workers, queues, scheduled operations, metrics, logs, traces, and alerts;
* data-plane connectivity and configuration convergence;
* error rate, latency, saturation, and business checks during the observation period.

Health endpoints alone do not prove that tenant configuration or traffic behavior is correct. Keep the upgrade open until route-level and business acceptance checks pass.

## Upgrade procedure

1. Freeze or reconcile administrative changes for the duration of the upgrade.
2. Confirm that backups, snapshots, acceptance checks, and the rollback decision point are current.
3. Apply required prerequisite or data migrations in the order stated in the release notes.
4. Upgrade with the supported deployment method and versions pinned to the approved release.
5. Wait for each required component and migration job to become healthy before moving to the next stage or increasing traffic.
6. Run the acceptance checks and observe the release for the agreed period.
7. Stop the rollout on data-integrity risk, tenant leakage, authentication divergence, sustained SLO regression, failed migrations, or loss of rollback capability.
8. Record the installed versions, verification results, observed impact, and final accept-or-rollback decision.

## Deprecation and support

Release notes and the applicable customer support policy state support status, deprecation milestones, security-fix availability, and end-of-support dates. Plan an upgrade before the installed version or any dependency reaches end of support.

When a feature is deprecated, the notice identifies the affected contract, replacement, migration steps, and planned removal version or date. Treat deprecation warnings as upgrade work; do not wait until removal to test the replacement. Support can require reproduction on a currently supported patch release.

## Rollback guidance

Workload, configuration, and data rollback are separate decisions. Before changing versions, confirm whether the target release changes stored data or configuration in a way that the previous version cannot read.

* For a workload-only regression, return to the previously verified product and chart versions only when release notes confirm data compatibility.
* For configuration changes, review the recorded diff and use the approved Kangal snapshot or a forward correction.
* For data changes, follow the database recovery procedure and its write-freeze and reconciliation requirements.
* Do not run older components against a newer, incompatible schema or partially completed migration.

After rollback, repeat health, route, worker, data-plane, observability, and business checks. Preserve the failed upgrade evidence and address the cause in a newer patch or an approved support plan before retrying.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kangal.dev/reference/release-lifecycle.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.