# OCSv3: one contract for cloud services

OCSv3 is an open contract between a cloud platform and the services it runs. It describes how the platform discovers a service, checks access, connects billing, records evidence and handles lifecycle operations, without knowing how the service is built.

> Sources: [What is OCSv3?](https://github.com/opencloudtech/CloudRING/blob/main/docs/what-is-ocsv3.md) and the [README](https://github.com/opencloudtech/CloudRING/blob/main/README.md#ocsv3-one-contract-for-cloud-services).

OCSv3 stands for Open Cloud Standard 3, a specification written by the CloudRING project. It isn't an accredited international standard or a certification scheme.

## What a service declares

A conforming module declares:

- its API, controller and lifecycle behaviour;
- its tenant, project, IAM and dependency model;
- portal extension and automation interfaces;
- meters, billing linkage, quota and capacity needs;
- health, readiness, observability, support and product analytics;
- durability, backup, restore, upgrade, rollback, export and deletion behaviour;
- distribution, federation, compatibility and commercial metadata.

The wire contracts are meant to be language-neutral. The reference implementation is written in Go and targets upstream Kubernetes APIs. A service becomes portable through stable APIs, events, packages and evidence that another conforming platform can check and operate.

## Three ways to run a service

| Profile | What it needs | Notes |
|---|---|---|
| `local` | A versioned public product API inside the provider's trust boundary | Kubernetes bindings are allowed when the implementation uses Kubernetes. |
| `remote` | The product API plus a remote endpoint, workload identity, trust, health and retry contract | No local Kubernetes binding is needed. |
| `api-only` | The product API plus endpoint, workload identity, trust, health and retry references | No Kubernetes binding or portal extension is needed. |

A signed, integrity-pinned, sandboxed portal extension is optional in every profile. Remote and API-only products declare endpoint, trust and health references, never raw endpoints or credentials.

## Why the Kubernetes API isn't enough

Kubernetes is one supported substrate. It doesn't define a product catalogue, tenant entitlements, billing meters, support diagnostics, portal extensions or the evidence a platform needs before it calls a service ready. OCSv3 adds those pieces without forcing a remote or API-only product to run Kubernetes itself.

Compared with the Open Service Broker API, OCSv3 covers more than provisioning and binding. It also covers the portal, billing, IAM, evidence, support, analytics and rollback.

## Try it

> The module in this example is synthetic. A passing check validates the package, not a real deployment.

```bash
git clone https://github.com/opencloudtech/CloudRING.git
cd CloudRING
go run ./cmd/ocsctl validate ./reference/synthetic-service/module-package.json
go run ./cmd/ocsctl conformance ./reference/synthetic-service/module-package.json
```

The [developer guide](https://github.com/opencloudtech/CloudRING/blob/main/docs/developer-guide.md), the [module authoring guide](https://github.com/opencloudtech/CloudRING/blob/main/docs/module-authoring.md) and the [conformance guide](https://github.com/opencloudtech/CloudRING/blob/main/docs/conformance.md) go further.

## Status

> Sources: [CURRENT_STATE.md](https://github.com/opencloudtech/CloudRING/blob/main/roadmap/CURRENT_STATE.md) and [roadmap.yaml](https://github.com/opencloudtech/CloudRING/blob/main/roadmap/roadmap.yaml).

The package types, validators, Go SDK and conformance tooling exist as reference and experimental code. A release candidate of the contract is roadmap goal G07. It follows the goals for the operation kernel, identity, IAM and provider operations.

## Propose a change

Changes to OCSv3 follow the process in [GOVERNANCE.md](https://github.com/opencloudtech/CloudRING/blob/main/GOVERNANCE.md#changes-to-governance-or-ocsv3). A proposal states the problem and who it affects. It documents the compatibility, security, ownership and exit consequences, and gives a migration path when existing contracts change. The documents and the machine-readable contracts are then updated together. Start with an [issue](https://github.com/opencloudtech/CloudRING/issues).