Quality Criteria
This page defines the quality criteria a ServiceProvider should aim for to be ready for use in different kinds of OpenControlPlane landscapes, from early-stage experiments to production environments with corporate compliance requirements.
Use this page as a starting point: it tells you which criteria to implement and helps you understand what maturity level your service provider is at.
The criteria are tooling-agnostic. They describe what a service provider must produce (its artifacts) and how it must behave (at runtime), not how it is built. Service providers in any GitHub organisation can adhere to them, regardless of the build system or CI they use.
Tiers at a glance
| Tier | Suitable for | Not suitable for |
|---|---|---|
 | Proof-of-concept, evaluation, contributor hacking | Anything you don't want to clean up by hand if it breaks |
 | Dev/test landscapes, internal platforms, situations where rough edges are tolerable | Regulated or production environments without additional review |
 | Production landscapes, customer-facing platforms, corporate / air-gapped environments |
The tiers are a rough indicator of maturity and will gain more meaning over time. For now, use the criteria below as a checklist for what to implement, independent of which tier you are aiming for.
The quality criteria
1. Deletion behaviour
When a user requests to uninstall a service through the ServiceProviderAPI, the service provider must not blindly remove the service and its CRDs from the managed ControlPlane. Services like Crossplane, Flux, or ESO install CRDs into the ControlPlane, and users may have created instances of those CRDs. Deleting the CRDs while custom resources still exist would leave those resources orphaned in the cluster or cause managed resources in external systems to escape the platform's control.
Before uninstalling, the service provider checks whether any custom resources belonging to the domain service still exist on the managed ControlPlane. If they do, the provider blocks deletion and surfaces a clear message explaining what needs to be cleaned up first.
2. Status reporting and error messages
Every ServiceProviderAPI reconciled by the service provider carries a Status.Phase (Ready / Progressing / Terminating) and typed Conditions (at minimum Ready, plus type-specific ones). Conditions follow the metav1.Condition shape with reason and message. See the status reporting guidelines for the expected conventions.
When reconciliation fails, the cause appears on a Condition's message and as a Kubernetes Event on the ServiceProviderAPI. Messages are actionable: they name the missing or invalid input, or the underlying system that failed.
3. Operation annotations
The service provider honours the operation annotations defined in the controller guidelines. These annotations allow platform owners and end users to pause or force-reconcile a ServiceProviderAPI or ServiceProviderConfig without modifying its spec.
If you use the opencontrolplane-runtime package, this behaviour is implemented centrally in pkg/serviceprovider/apireconciler.go.
4. API stability policy
The provider declares its API maturity per CRD (v1alpha1, v1beta1, v1) and follows the matching change policy. Breaking changes at v1beta1+ require a deprecation cycle. Conversion webhooks exist when multiple versions are served. See the Kubernetes API conventions and API change guidelines for the expectations this criterion builds on.
5. Custom CA bundle support
The provider supports custom CA bundles so it can operate in air-gapped or corporate environments that use private certificate authorities. The CA bundle is propagated to all relevant components of the domain service, ensuring that outbound connections and external integrations trust the custom certificates.
6. Release artifacts
Each tagged release publishes a multi-architecture container image and an OCM component descriptor referencing that image. Both are pushed to a publicly resolvable registry. Without published artifacts, no landscape can install the provider through the OpenControlPlane onboarding system.
The openmcp-project/build repository provides reusable GitHub Actions workflows and Taskfiles that implement this build pipeline. The service-provider-template already wires these conventions in and is the recommended starting point for new providers.
7. Testing
The service provider is tested against a real cluster covering the full lifecycle: install, reconcile, and delete a DomainService in a ControlPlane. The openmcp-testing framework provides tooling for this within the OpenControlPlane ecosystem. A dedicated integration test suite to verify that a service provider is well-behaved is planned for the future.
8. Private OCI registry support
The provider supports pulling OCI artifacts from private registries by using registry credentials. Platform operators can reference credentials (for example through Kubernetes image pull secrets) without hardcoding them into manifests. Authentication failures are surfaced as actionable status conditions and events so operators can diagnose missing, invalid, or expired credentials quickly.
This can be achieved by using pre-built functions from openmcp-project/extensibility-utils or by using openmcp-project/platform-service-resource-replicator.
9. Ownership and maintenance documentation
A MAINTAINERS.md or CODEOWNERS file names responsible humans or teams. Contribution and issue reporting instructions are documented in CONTRIBUTING.md or the project README.
Declaring a tier in your service-provider repository
Each service-provider repository carries a Quality Criteria block in its README, placed directly below the title and badges and above the "About this project" section. It has three parts.
1. Tier badge
A badge showing the tier you claim. Copy the snippet for your tier from the Badge snippets section below and paste it into your README.
2. Self-assessment table
A table showing the status of every criterion. Three states:
- ✅ Met — the criterion is fully satisfied.
- ❌ Not met — the criterion is not satisfied.
- ⚠️ Partial — some aspects are met, with known gaps documented (link to a tracking issue if available).
Fill this in yourself based on your own assessment.
3. Link to the canonical criteria
A link back to this page so anyone reading the table can find the definitions.
Example
## Quality Criteria
| Criterion | Status |
| --------------------------------- | :----: |
| Deletion behaviour | ✅ |
| Status reporting & error messages | ✅ |
| Operation annotations | ✅ |
| API stability policy | ✅ |
| Custom CA support | ❌ |
| Release artifacts (image + OCM) | ✅ |
| Testing | ✅ |
| Private OCI registry support | ❌ |
| Ownership and maintenance docs | ✅ |
See the [OpenControlPlane Quality Criteria](https://open-control-plane.io/developers/serviceprovider/quality-criteria) for definitions.
Badge snippets
Copy the badge for your tier and paste it into your README directly below the ## Quality Criteria heading:
Experimental
[](https://open-control-plane.io/developers/serviceprovider/quality-criteria)
Incubating
[](https://open-control-plane.io/developers/serviceprovider/quality-criteria)
Stable
[](https://open-control-plane.io/developers/serviceprovider/quality-criteria)
These render identically on GitHub, GitLab, and the OpenControlPlane docs site.