Score

kubernetes/extras platformengineering/score platformengineering

“Configure once. Deploy anywhere. From local to prod.”

Core Idea

Score is a platform-agnostic workload spec: describe how your app runs once in score.yaml, then a Score implementation translates it to Docker Compose, Kubernetes manifests, or Helm charts for any environment.

• The problem: rewriting configs per environment; the philosophy: workload-centric development.
• How it works: the spec file, a Score implementation CLI, and generated platform configuration files.
• Official and community implementations, plus how it slots into your workflow.

What is Score?

Score is a developer-centric, platform-agnostic, container-based workload specification. It lets you define how a workload should run in a single score.yaml file, then use a Score Implementation CLI to translate that file into platform-specific configuration (Docker Compose, Kubernetes manifests, Helm charts, etc.).

The core promise: write your workload configuration once, and deploy it anywhere — local dev, staging, or production — without rewriting configs for each environment.

The Problem It Solves

Cloud-native developers face several recurring pain points:

Problem	Description
Cognitive overload	Devs must become experts in Docker Compose, Helm, Kubernetes, and more just to deploy a simple change
Config drift	Multiple environment-specific config files get out of sync, increasing misconfiguration risk
YAML bloat	Maintaining many environment-specific config files leads to repetitive work and sprawling YAML
Infra-centric workflow	Platform/tooling concerns bleed into developer responsibility, slowing feature delivery
Example scenario: You use Docker Compose locally but Helm Charts for your Kubernetes dev environment. You must know both tools deeply and keep them in sync — a multi-stakeholder, error-prone process.

The Score Philosophy (Workload-Centric Development)

Score advocates for a workload-centric (vs. infra-centric) development approach, built on three principles:

1. Single source of truth — one score.yaml file defines how the workload runs, independently of the target platform.
2. Tightly scoped spec — shields developers from the complexity of container orchestrators by exposing only core workload constructs.
3. Declarative infrastructure — developers declare what their workload needs (e.g., “a Postgres database”); the platform decides how to provision it.

Key Characteristics

• Platform-agnostic — integrates with Docker Compose, Kubernetes, Helm, Google Cloud Run, Fly.io, and more.
• Environment-agnostic — score.yaml captures stable config; environment-specific values are injected at deploy time.
• Tightly scoped — describes workload-level properties only; not a full YAML replacement for any specific platform.
• Declarative — developers state resource dependencies (e.g., type: postgres); the target environment handles provisioning.
• Open source — freely available, community-driven, and backed by CNCF.

How Score Works

There are three components in the Score workflow:

score.yaml  →  Score Implementation CLI  →  Platform Config Files  →  Deploy

1. The score.yaml File

A single declarative spec file placed alongside source code in version control. Defines containers, ports, environment variables, and resource dependencies.

2. A Score Implementation (CLI)

A CLI tool that reads score.yaml and generates platform-specific configuration. Implementations are typically maintained by platform teams.

Official implementations:

• score-compose — generates Docker Compose files
• score-k8s — generates Kubernetes manifests

3. Platform Configuration Files

The generated files (e.g., docker-compose.yaml, Kubernetes YAML) are executed natively by the target platform, optionally combined with environment-specific parameters.

Example score.yaml

apiVersion: score.dev/v1b1
metadata:
  name: sample
 
containers:
  main:
    image: .
    variables:
      # Resource outputs are injected as env vars; secrets are handled securely
      PG_CONNECTION_STRING: "postgresql://${resources.db.username}:${resources.db.password}@${resources.db.host}:${resources.db.port}/${resources.db.database}?sslmode=disable"
 
service:
  ports:
    www:
      port: 8000
      targetPort: 80
 
resources:
  db:
    type: postgres    # Declare the need; the platform provisions it
  dns:
    type: dns
  route:
    type: route
    params:
      host: ${resources.dns.host}
      path: /
      port: 8080

Key observations:

• No Docker- or Kubernetes-specific syntax in the spec itself
• Resource connection strings are parameterized (${resources.db.host}) — values are injected per environment
• The resources block simply declares what is needed, not how to create it

Score Implementations

Official

Implementation	Target Platform	Notes
score-compose	Docker Compose	For local development
score-k8s	Kubernetes	For remote/production clusters

Community / Other

The spec is open, so platform teams and the community can build their own implementations (e.g., for Fly.io, Google Cloud Run, Nomad, etc.). A guide for creating custom implementations is available in the docs.

Workflow Integration

• Version control — score.yaml lives alongside source code in the repo
• CI/CD — Score CLI commands can be automated in GitHub Actions or any CI/CD pipeline
• Dev Containers — supported for containerized development environments
• Overrides — score.yaml supports environment-specific overrides and platform-specific extensions without modifying the base spec
• IDE support — JSON schema linter/autocomplete available for IDE integration

Docs Structure (docs.score.dev)

• Get started — step-by-step quickstart guide
• Specification — full spec reference + schema reference + IDE linter setup
• Implementations — score-compose and score-k8s docs (installation, CLI reference, resource provisioners, patch templates)
• Examples — Nginx, Node.js + PostgreSQL, Dapr, Microservices, Backstage, Frontend & Backend, LLM Models, Microcks
• How-to guides — GitHub Actions, CI/CD pipelines, Dev Containers, Overrides, Kind cluster setup

Community & Ecosystem

• CNCF Sandbox project (accepted into the Cloud Native Computing Foundation)
• Slack: #score channel on CNCF Slack (https://slack.cncf.io)
• Twitter/X: @score_dev
• GitHub org: https://github.com/score-spec
• Email: team@score.dev
• Built with backing from Humanitec

Developer Testimonials

“I love the idea of being able to describe everything my workload needs in one file.” — Marius Tolzmann, CTO at Mineiros

“Score allows to describe what a workload needs to run and can be utilized throughout the entire development lifecycle.” — Min Kim, Cloud Architect at Frontside Software

“Running my first transform was such a fun ‘aha’-moment — I ran everything locally on Docker and pushed it to Kubernetes.” — Marius Raesener, Tech Lead at BAUHAUS Deutschland

Quick Reference

# Install score-compose (example)
brew install score-spec/tap/score-compose
 
# Initialize a Score project
score-compose init
 
# Generate Docker Compose config from score.yaml
score-compose generate score.yaml
 
# Run the workload
docker compose up

# For Kubernetes (score-k8s)
score-k8s init
score-k8s generate score.yaml
kubectl apply -f .score-k8s/manifests.yaml

Summary

Score is essentially a lingua franca for workload configuration — a thin abstraction layer that sits between developer intent and platform implementation. By writing a single score.yaml, development teams can:

• Eliminate environment-specific config sprawl
• Reduce cognitive load on developers
• Enable platform teams to own infrastructure concerns independently
• Move faster from local development to production with consistent configuration

---

Website: https://score.dev
GitHub: https://github.com/score-spec/spec
Docs: https://docs.score.dev/docs/
Community: #score on CNCF Slack
Status: CNCF (Cloud Native Computing Foundation) Sandbox project
License: Open Source