|
| 1 | +# KubeBlocks Maturity Levels |
| 2 | + |
| 3 | +KubeBlocks uses a three-tier maturity model to communicate API stability and |
| 4 | +release-process maturity. The current level is shown as a badge in |
| 5 | +[`README.md`](../README.md). The badge does not measure production adoption by |
| 6 | +itself; adoption evidence is one input to maturity changes. |
| 7 | + |
| 8 | +The criteria below separate hard gates from evidence requirements. API version, |
| 9 | +security, release-process, and approval requirements are hard gates. Adoption, |
| 10 | +test coverage, and upgrade history require linked evidence and maintainer |
| 11 | +judgment during the level-change review. |
| 12 | + |
| 13 | +## Levels |
| 14 | + |
| 15 | +### Alpha |
| 16 | + |
| 17 | +- **Meaning**: Early development. APIs and CRDs may change in breaking ways |
| 18 | + between minor releases. Features may be incomplete or experimental. |
| 19 | +- **Color**: `red` |
| 20 | +- **Criteria**: |
| 21 | + - Some served CRD groups may still be `v1alpha1` or `v1beta1`. |
| 22 | + - Production deployments may be limited or concentrated in early adopters. |
| 23 | + - Test coverage is growing but has not met the Beta evidence bar. |
| 24 | + - Upgrade and rollback paths may not yet have broad production evidence. |
| 25 | + |
| 26 | +### Beta |
| 27 | + |
| 28 | +- **Meaning**: Feature-complete and production-tried. APIs are mostly stable; |
| 29 | + breaking changes are discouraged and require a deprecation notice. |
| 30 | +- **Color**: `orange` |
| 31 | +- **Criteria**: |
| 32 | + - Core CRDs are at `v1`. Core CRDs are the `apps.kubeblocks.io/v1` and |
| 33 | + `workloads.kubeblocks.io/v1` resources listed in the current API snapshot. |
| 34 | + - Multiple production deployments across different industries are documented |
| 35 | + in the level-change issue. |
| 36 | + - CI covers unit, integration (envtest), and e2e tests, with coverage accepted |
| 37 | + by the reviewing maintainers. |
| 38 | + - Upgrade and rollback have linked production or release-validation evidence. |
| 39 | + - [`SECURITY.md`](../SECURITY.md) is published and vulnerabilities are tracked. |
| 40 | + |
| 41 | +### Stable / GA (General Availability) |
| 42 | + |
| 43 | +- **Meaning**: Production-grade. APIs are stable with backward-compatibility |
| 44 | + guarantees following semantic versioning. |
| 45 | +- **Color**: `green` |
| 46 | +- **Criteria**: |
| 47 | + - All stable-track CRD groups are at `v1`, and no breaking changes are |
| 48 | + planned. |
| 49 | + - Widespread production adoption with documented case studies. |
| 50 | + - Comprehensive test coverage including upgrade/downgrade matrices. |
| 51 | + - Formal release process with LTS support windows. |
| 52 | + - Security audits performed; SBOM published per release. |
| 53 | + |
| 54 | +## How to Change the Maturity Level |
| 55 | + |
| 56 | +1. Open a GitHub issue proposing the level change with evidence that the |
| 57 | + target level's criteria are met. |
| 58 | +2. Maintainers review the proposal. At least two maintainer approvals are |
| 59 | + required. Maintainers are listed in [`MAINTAINERS.md`](../MAINTAINERS.md). |
| 60 | +3. On approval, update the badge line in `README.md` and the status text in |
| 61 | + this document: |
| 62 | + |
| 63 | + ``` |
| 64 | +  |
| 65 | + ``` |
| 66 | + |
| 67 | + | Level | `message` | `color` | |
| 68 | + |-------|-----------|---------| |
| 69 | + | Alpha | `alpha` | `red` | |
| 70 | + | Beta | `beta` | `orange` | |
| 71 | + | Stable| `stable` | `green` | |
| 72 | + |
| 73 | +4. The change is included in the next release notes. |
| 74 | + |
| 75 | +## Current Status |
| 76 | + |
| 77 | +KubeBlocks is currently at **Alpha**. The project is used in production by |
| 78 | +internet companies, financial institutions, telecom carriers, and SaaS |
| 79 | +providers, and the addon ecosystem spans 35+ database engines. |
| 80 | + |
| 81 | +API version snapshot as of the `main` branch at the time this document was |
| 82 | +added. The `apis/` directory and CRD manifests under `config/crd/bases/` remain |
| 83 | +the source of truth. |
| 84 | + |
| 85 | +| API group | Served versions | Key resources | |
| 86 | +|-----------|-----------------|---------------| |
| 87 | +| `apps.kubeblocks.io` | `v1` (primary); `v1beta1`, `v1alpha1` also served for legacy kinds | `Cluster`, `Component`, `ClusterDefinition`, `ComponentDefinition`, `ComponentVersion`, `ServiceDescriptor`, `ShardingDefinition`, `SidecarDefinition`; `ConfigConstraint` (`v1beta1`, `v1alpha1`); `Rollout`, `Configuration` (`v1alpha1`) | |
| 88 | +| `workloads.kubeblocks.io` | `v1` | `InstanceSet`, `Instance` | |
| 89 | +| `dataprotection.kubeblocks.io` | `v1alpha1` | `Backup`, `Restore`, `BackupPolicy`, `BackupSchedule`, `BackupPolicyTemplate`, `ActionSet`, `BackupRepo`, `StorageProvider` | |
| 90 | +| `operations.kubeblocks.io` | `v1alpha1` | `OpsRequest`, `OpsDefinition` | |
| 91 | +| `parameters.kubeblocks.io` | `v1alpha1` | `Parameter`, `ComponentParameter`, `ParametersDefinition`, `ParamConfigRenderer`, `ParameterView` | |
| 92 | +| `extensions.kubeblocks.io` | `v1alpha1` | `Addon` | |
| 93 | +| `experimental.kubeblocks.io` | `v1alpha1` | `NodeCountScaler` | |
| 94 | +| `trace.kubeblocks.io` | `v1` | `ReconciliationTrace` | |
| 95 | + |
| 96 | +The current core CRDs already meet the Beta API-version gate, but the project |
| 97 | +remains **Alpha** until all Beta evidence requirements are reviewed and |
| 98 | +approved. Promoting the remaining `v1alpha1` groups to `v1` is a Stable / GA |
| 99 | +prerequisite tracked per group. |
0 commit comments