Define a Kubernetes CRD for Score (contract only; controller left to platforms)

[cappyzawa]

TL;DR: The CLI is great for Day‑1 manifest generation, but once apps are running we often drop down to Kubernetes primitives. In practice, knowing the Score spec is enough to create, but not enough to operate. I propose defining a Kubernetes CRD schema/contract for Score so users can stay at the Score abstraction for both creation and Day‑2 (get/describe/apply/patch/scale), with unified status and cleaner RBAC/audit. Controllers/operators remain platform‑specific and out of scope for score-spec.

Problem / Motivation

• Today, the CLI approach excels at generating manifests, but post‑deployment teams still reason about Deployment / Service / Ingress (or other platform‑specific objects) directly.
• This leaks platform details back to app teams. The Score spec is sufficient to create an app, but not to operate it in a Score‑native way.

Proposal (contract only)

Define a Score CRD schema in score-spec that implementations can target. The CRD would either embed or reference the Score spec verbatim (e.g., generic git/oci ref). The contract would cover:

• Label/annotation conventions to propagate to generated children.
• status shape with conditions/summary, exposed endpoints, resource bindings (e.g., connection strings), and a stable pod selector for logs.
• Optional scale subresource and recommended additionalPrinterColumns for discoverability.

Note: Any examples like reconciling Deployment/Service/Ingress are purely illustrative. The CRD must not prescribe child kinds. Platforms may reconcile their own App CRDs, StatefulSet/Job, Gateway API routes, service‑mesh objects, Knative/serverless targets, or anything else. The value is keeping users at the Score abstraction while letting platforms choose backends.

Out of scope (by design)

• Controllers/operators: left to platforms and implementations, not score-spec.
• Logs/exec: naturally out of scope for a CRD. Like generate, these can live in a thin, platform‑provided CLI wrapper that leverages the CRD’s discoverability (selectors/endpoints).

Questions for maintainers

• Is defining such a CRD schema/contract in scope for score-spec?
• If not, would you consider blessing an out‑of‑tree community CRD so different platforms can align on a single contract?

If helpful, I’m willing to take a first pass at a minimal CRD schema (and, separately, an out‑of‑tree controller skeleton) and iterate with the community.

[mathieu-benoit]

Hi @cappyzawa, thanks for the detailed dicsussion and proposal, this was very helpful for us, as Maintainers, to review it during our Score Community meeting earlier today: #158 (comment).

We agreed that this is indeed a perfect scenario and opportunity to have a Score implementation driven by the community.

The idea for you to start is to have this repo(s) outside of the https://github.com/score-spec Org.

From there, you can iterate with the Score maintainers, contributors and community in order to make progress with it.

We really like the idea (GitOps with Score has been asked/raised couple of times) and we also think that your approach to start small with the CRD first and iterate with small controller, etc. is the best way to make it land somewhere.

In one month, that's our next Score Community Meeting (#160), why not coming presenting where you will be with your first iteration with the CRD?

Feel free to drop us a note, your questions, updates in our CNCF Slack channel, it will be our pleasure to support you on this.

[cappyzawa]

@mathieu-benoit Thanks for the invitation! I’d love to present, but I just realized I have a family trip on that day and won’t be able to join the next community meeting (#160).

In the meantime, you can try a minimal end-to-end flow via the “Getting Started” guide here:
https://github.com/cappyzawa/score-orchestrator/tree/main/docs/guides/getting-started.md

Thanks for your feedback .

[mathieu-benoit]

@cappyzawa, thanks for the heads up and no worries at all!

I just left a note to be discussed during the meeting later this week #160 to ask if there is any volunteer in the community to go through your gettting started guide.

JFYI, next community meeting will be on Nov 6th, 2025: #163 in case you will be able to make it.

[cappyzawa]

Thanks for the thoughtful feedback and for discussing this in the community meeting!
I’m happy to kick things off outside the main org and will share progress and any questions in Slack as I go.

I’ll aim to have a minimal CRD schema ready to show by the next community meeting. Appreciate the support—looking forward to collaborating further!

[devantler]

@cappyzawa how do you propose extending the spec with defaults for platform related stuff like (Policies, SecurityContexts etc etc).

I know this is not super relevant in the first iteration of the approach, but I know it is something that will become a bottleneck if not well supported. Ideally I think the responsibilities should be as such:

• devs define a Score spec without all the K8s complexities and the operator reconciles it
• ops/platform teams host the operator and define defaults to ensure reconciled Score specs are extended with the necessary configuration to make it secure and compliant with orgs preferred level of security, standardization and compliance.

If we can find a way to solve the latter in an elegant way, I think this could become super relevant in many orgs trying to solve the complexity barrier between devs and modern platform engineering. If not I am worried that it will become niche, and lack the flexibility to be deemed a feasible OS option to comparable tooling built in-orgs.

---

My thought would be to make the operator a configurable Helm Chart where these defaults can be provided via flexible configuration. I think this fits well in the ops domain.

Finding out what "flexible configuration" means would be the biggest part of this task IMO.

[cappyzawa]

TL;DR
My initial idea was: Score Official provides CRDs only and platforms implement controllers. After weighing the trade-offs, I believe that to keep platform flexibility & safety while giving users a consistent abstract interface, we need CRDs + a reference Controller (Orchestrator). That’s the direction I’m pursuing now (rationale in ADR-0002).

Overall shape

• Users author only Workload (no runtime-specific knobs).
• An Orchestrator applies platform policy, resolves dependencies, produces a runtime-agnostic execution plan, and is the single writer of Workload.status with a minimal, abstract surface (one endpoint URI + abstract conditions).
• Runtime controllers consume the plan and dependency outputs to materialize on the chosen platform (Kubernetes/ECS/Nomad/…), and write detailed diagnostics to their own internal objects (not to Workload.status).
• Dependency providers (DB, queue, storage, image build, etc.) publish consumable outputs that the plan projects into the workload.
• Flow (high level):

User applies Workload
  ↓
Orchestrator
  ├─ apply PlatformPolicy (PF defaults/guardrails)
  ├─ resolve dependencies
  ├─ emit execution plan (runtime-agnostic)
  └─ single-writer of Workload.status → one endpoint URI + abstract conditions
         ▲
         │ consumes plan + dependency outputs
Runtime controller(s) ───────────────────────────▶ materialize on chosen platform
         │                                           (Kubernetes / ECS / …)
         └──────── dependency providers publish outputs (URI / secret / image / cert)

Full spec (concise; happy to quote relevant bits here as needed):
https://github.com/cappyzawa/score-orchestrator/tree/main/docs/spec

Actors & roles

• Score Official (or community, initially): provide a small set of CRDs and a reference Orchestrator.
• Platform teams (PF/vendors): implement dependency providers and, if needed, runtime controllers.
• Users (app devs): author Workload only.

Design highlights (what I’m validating in code now)

• Single-writer: only the Orchestrator updates Workload.status.
• Minimal status: status.endpoint is a single canonical URI; conditions use abstract types/reasons (no runtime nouns).
• Validation boundary: CRD OpenAPI+CEL for spec invariants; Admission (VAP/OPA/Kyverno) for org policies.
• Visibility: internal contracts (e.g., dependency & plan objects) exist but are hidden by RBAC; users only see Workload.

I’ve started implementing an Orchestrator MVP to exercise the end-to-end path (single-writer semantics, endpoint reflection, abstract vocabulary) with a thin Kubernetes runtime adapter and stub dependency providers.

Feedback welcome on anything—direction, actor split, status surface, policy layering, naming, or any other angle. I’m happy to adapt and bring excerpts from the spec into this thread where useful.

[cappyzawa]

@devantler

Great point. I’m aiming for this split:

• PlatformPolicy (PF-facing, not user-visible): declare runtime class, security baseline (container/pod posture), exposure/network policy, and projection defaults. Select by labels/namespaces so ops can scope per team/env.
• Admission (VAP/OPA/Kyverno): enforce org governance—registry allow-lists, naming, quotas, approvals—without leaking runtime knobs into Workload.
• Helm values vs policy layering: chart values set cluster-wide defaults for the operator; per-tenant/namespace overrides live in PlatformPolicy. (Intended precedence: Helm < cluster policy < namespace policy.)
• Runtime translation: the runtime controller turns policy + plan into concrete platform objects (e.g., on Kubernetes, SecurityContext/NetworkPolicy), while Workload stays abstract.

If you have better ideas for precedence/selection semantics or gaps we should cover, I’d love to hear them.

[devantler]

I like it alot! As I understand it adopting score with this setup will result in the following responsibilities being added to actors

• Platform Teams: will manage a new chart (operator for Workloads, PlatformPolicies, and related CRs), build dependency providers (primary way to extend workload capabilities), and ensure compliance with existing Policy Engine (admission). Rest seems like advanced use.
• App Teams: will manage Workloads, and maybe in some case own namespace scoped policies (admission, PlatformPolicy).

Please help me understand if this is totally wrong 🙏

I have a few questions, to help me understand it all better:

• Is it possible to see the PlatformPolicy CRD today?
• Is the name for PlatformPolicy decided? WorkloadPolicy seems more logical to me, and fits well with Score already having coined apps as Workloads. Platform is a bit of an umbrella term today, and I could see this causing some confusion.
• How do I build a dependency provider for Score with K8s?
• Is the code public, I would love to follow along, and possibly contribute.

[cappyzawa]

Sorry for the late reply!

Thanks for the thoughtful questions — and your understanding is mostly spot-on. One nuance up front: PlatformPolicy is platform-owned, cluster-scoped, and hidden from app teams via RBAC. App teams author only Workload. If an org wants namespace-scoped guardrails, that typically lives in Admission (VAP / OPA Gatekeeper / Kyverno), not in PlatformPolicy.

Responsibilities (as I see them)

• Platform teams: run the chart (operator for Workload, PlatformPolicy, and internal CRs), build dependency providers (Resolvers), and enforce org policy via Admission.
• App teams: manage Workload only. (Namespace-scoped policy can be delegated via Admission if your org chooses, but PlatformPolicy itself stays PF-facing.)

---

A1) Can I see the PlatformPolicy CRD today?

Yes — the type is defined here:
https://github.com/cappyzawa/score-orchestrator/blob/main/api/v1b1/platformpolicy_types.go
I have the docs and types in place; some parts of the implementation are still evolving.

A2) Is “PlatformPolicy” the final name?

I’m currently using PlatformPolicy to signal platform-owned defaults/guardrails.
“WorkloadPolicy” tends to read as something app teams would tweak per workload, which I want to avoid. That said, I’m not attached to the name — if you have a clearer term that still conveys platform-owned, cluster-scoped, consumed by the Orchestrator (not user-tweakable), I’d love to adopt it.
(Names I considered: OrchestrationPolicy, PlatformDefaults, MaterializationPolicy.)

A3) How do I build a dependency provider on K8s?

I published a minimal reference Resolver you can copy: “static-uri” (PR #5).
It watches ResourceBindings and projects spec.params.uri to status.outputs.uri using the standard outputs shape, with idempotent reconcile and lean RBAC:
cappyzawa/score-orchestrator#5

Recipe (short):

1. Watch ResourceBinding filtered by the spec.type(s) you support.
2. Provision/attach the backing resource (operator or cloud API).
3. Publish status.outputs (one or more of: secretRef, configMapRef, uri, image, cert) and set outputsAvailable=true / success state.
4. Honor deprovisionPolicy on deletion.
   👉 A Resolver never writes Workload.status (single-writer = Orchestrator).

A4) Is the code public?

Yes — the repo is here (docs + types; I’m iterating the implementation):
https://github.com/cappyzawa/score-orchestrator

If you have a favorite name for the policy CRD that nails the platform-owned, cluster-scoped intent without inviting user-side editing, I’m all ears.

[cappyzawa]

Quick update/correction to my previous reply — I finalized ADR-0003 and the design evolved. Sharing the changes here for the record (no action required).

What changed

• PlatformPolicy CRD → removed. Replaced by a non-CRD Orchestrator Configuration (profiles/backends/provisioners/defaults + deterministic selection pipeline). Guardrails and org rules stay in Admission (VAP / OPA Gatekeeper / Kyverno).
• ResourceBinding → ResourceClaim. Same intent (internal contract with provisioners), clearer naming. The Orchestrator remains the single writer of Workload.status.
• Determinism & safety: profile selection/ordering is normative; production requires digest-pinned template/provisioner refs; validation split clarified (CRD OpenAPI+CEL for Workload, config is linted/schema-checked out-of-tree).

Updates to my earlier Q/As

• A1) “Can I see PlatformPolicy today?” -> Withdrawn: PlatformPolicy is no longer part of the design. Please see the Orchestrator Configuration spec instead.
• A2) “Is PlatformPolicy the final name?” -> N/A now; the concept is replaced by the non-CRD config (docs below).
• A3) “How to build a dependency provider?” -> Still valid with a naming tweak:
  • Watch ResourceClaim for the resource types you support
  • Provision/attach the backing resource
  • Publish standardized status.outputs (secretRef, configMapRef, uri, image, cert) and set outputsAvailable=true
  • Honor deprovisionPolicy on deletion
    (A provisioner never writes Workload.status; single-writer stays the Orchestrator.)
• A4) “Is the code public?” -> Yes. Links below.

Docs (docs-first; no code required to read)

• Orchestrator Configuration:
  https://github.com/cappyzawa/score-orchestrator/blob/main/docs/spec/orchestrator-config.md
• CRDs (incl. Workload, ResourceClaim, WorkloadPlan):
  https://github.com/cappyzawa/score-orchestrator/blob/main/docs/spec/crds.md
• ADR-0003 (rationale):
  https://github.com/cappyzawa/score-orchestrator/blob/main/docs/ADR/ADR-0003-architecture-simplification.md

Happy to keep iterating independently; this message only corrects the record from my previous comment.

[mathieu-benoit]

Wow, super great progress already, nice!

Couple of food for thoughts:

1. Workload CRD makes sense as the translation/mapping of the Score file, facing to the Devs.
2. With this above, a little controller could already be implemented, just to deploy let's say first a default Deployment based on the Score file/spec/CRD.
3. But at this stage, already a question, so now the Devs will author their Workload spec via the new CR file, not anymore the Score file as of today? Do we need a translation/generator from one to the other? Or should we also allow score-compose and score-k8s as examples, to support this new file format as inputs of score-* generate? I'm looking at how the seemless experience could be anticipated here. That's appealing to be able to switch from one implementation to another, seemlessly. Assuming that this new Score Operator/Controller is yet another Score implementation. It's maybe out of scope of this motion here, but I think we need to capture this.
4. PlatformPolicy CR: I'm not sure here, I'm confused with the other WorkloadPlan CR. Let me share some thoughts here. What has been discussed with score-k8s as good feedback is that the default Deployment is not always what the PEs want. That's why we now have the patch templates. But something that we could have in addition or in place (doesn't exist yet), is more the notion of WorkloadProfile. I think that could be a good opportunity to have this as a CR. Meaning that PEs could do something like this instead score-k8s init --workload-profile file://deployment --workload-profile file://job --workload-profile file://knative-service --workload-profile file://kro-rgd --workload-profile file://crossplane-app-composition --workload-profile file://kratix-app. The goal is to generate the actual Kubernetes resources from the Workload CR and based on the selected WorkloadProfile. The intent is to support multiple WorkloadProfiles, one by default, and maybe a field or an annotation on the Workload CR that the Dev could explicitly ask to target. Also, we should support a template mechanism (as opposed to golang func) in order to be flexible/extensible. Open questions: Kubernetes manifests, Helm charts, etc. support?
5. ResourceBinding CR, I think that's similar to the score-k8s's provisioners? If that's the case for the name maybe something like ResourceDefinition (or ResourceProvisioner or ResourceRecipe)? For one resource type, you can have multiple definitions, based on label(s) on the namespace for example: dev versus staging versus prod? And maybe other rules as selectors? Another thing to think of is about the concrete definition/implementation: do we want to support k8s manifests templates only? And maybe Helm charts? And maybe not the current cmd one? Also we need to anticipate that sometimes, these resource definitions could be entirely skipped in the case of Crossplane, Kro, Kratix, because their own CR will actually generate all the resources dependencies, not anymore the responsability of the resource provisioner per se.
6. For the Admission and Policy mentioned above, I don't think that it should be part of this Score Operator implementation. It seems to be more something configured outside, like I need ArgoCD in my cluster, I need observability, I need admission controller for governance, etc.

@cappyzawa, let me know if this helps or if you need me to clarify some of the points shared above.

CC: @chris-stephenson @astromechza for capturing their thoughts too.

[cappyzawa]

@mathieu-benoit Thanks so much—super helpful feedback, and I’m glad we’re aligned.

Q1 — Workload CRD
Totally agree. Workload is the developer-facing, platform-neutral mapping of the Score file. Devs author only this; user-visible status stays minimal (single endpoint, abstract conditions, compact binding summaries).

Q2 — “tiny controller that just deploys a default Deployment”
I read this as a sample ask. I’ll keep the split Orchestrator → (internal) WorkloadPlan → Runtime, and I’m positive about a minimal K8s runtime adapter sample that emits a plain Deployment as an example (separate from the orchestrator core).

Q3 — Authoring flow (Score vs Workload) & seamlessness
Both paths are fine: continue authoring Score and generate/apply the Workload CR in tooling, or author Workload directly. It’s a near 1:1 mapping, so a generator would be straightforward; because both formats are simple, its priority can be low.

Q4 — PlatformPolicy / WorkloadPlan vs “WorkloadProfile”
Good point—I hadn’t captured the profile idea clearly. I’ll consider how to incorporate this.

Q5 — ResourceBinding vs score-k8s provisioners; naming
Understood. I’ll catch up on provisioners and consider simplifying the mapping and naming accordingly.

Q6 — Admission/Policy scope
Agreed: keep it outside the operator. CRDs enforce spec-level invariants (OpenAPI+CEL); org governance (registries, naming, quotas, etc.) lives in Admission (VAP / OPA Gatekeeper / Kyverno).

---

refs:

• PlatformPolicy type: https://github.com/cappyzawa/score-orchestrator/blob/main/api/v1b1/platformpolicy_types.go
• Repo: https://github.com/cappyzawa/score-orchestrator
• Minimal Resolver example (static-uri, PR Provide bash one-liner install script #5): feat: add static-uri Resolver implementation cappyzawa/score-orchestrator#5

[cappyzawa]

Thanks for your feedback—I revisited some of the specs based on your comments.
You can find the details here: https://github.com/cappyzawa/score-orchestrator/blob/main/docs/ADR/ADR-0003-architecture-simplification.md
Just a note: I'm documenting my own decisions in ADR format for clarity, but this doesn't mean it's a group consensus or anything official.