Overview

What is Score?

Score is an open-source, platform-agnostic, container-based workload specification. With Score, you can define your workload once using the Score Specification and then use a Score Implementation CLI to translate it to multiple platforms such as Docker Compose or Kubernetes.

Humanitec is an active contributor to the Score project and the Platform Orchestrator offers native support for Score, allowing for a seamless integration between the two.

Example

The score.yaml file in the example below describes a workload with a busybox container dependent on a PostgreSQL database and advertising two public ports, 80 and 8080:

apiVersion: score.dev/v1b1

metadata:
  name: example-service

containers:
  container-id:
    image: busybox
    command: ["/bin/sh"]
    args: ["-c", "while true; do echo Hello friend!; sleep 5; done"]
    variables:
        CONNECTION_STRING: postgresql://${resources.db.username}:${resources.db.password}@${resources.db.host}:${resources.db.port}/${resources.db.name}

service:
  ports:
    www:
      port: 80
      targetPort: 8080
    admin:
      port: 8080
      protocol: UDP

resources:
  db:
    type: postgres

Key Characteristics

The Score specification is characterised by being:

  • Platform-agnostic: The Score Specification is not tied to a specific platform, allowing integration with various container orchestration platforms and tooling. One such tool is the Humanitec Platform Orchestrator. Read more on the Orchestrator’s Score integration below.

  • Environment-agnostic: Score embraces dynamic configuration management. The score.yaml file captures the configuration that stays the same across all environments and thereby enforces a clear separation between environment-specific and environment-agnostic configurations. When used with the Platform Orchestrator, the same Score file can, and should, be used to deploy across all Environments of an Application.

  • Tightly scoped: Score describes workload level properties. It does not intend to be a fully featured YAML replacement for any platform. Instead, Score draws a line between developer-owned workload configuration and platform-owned infrastructure configuration.

  • Declarative: Developers declare what their workload requires to run as part of a Score file. The platform in the target environment is responsible for resolving individual runtime requirements. E.g. when developers request a database resource for use by their workload, that resource is provisioned by the Platform Orchestrator using a Resource Definition set up by the platform team for that purpose.

Learn more

Learn more about how Score works, its benefits, and explicit non-goals, in the Score documentation.

How do Score and the Platform Orchestrator work together?

In your Internal Developer Platform, Score provides a convenient way for developers to interact with the Platform Orchestrator.

The humctl CLI offers a range of features for working with Score files.

Due to its platform-agnostic nature, Score can be utilised throughout the entire developer workflow. When using Score alongside the Humanitec Platform Orchestrator, the process may look like this:

  • Developers use a Score implementation such as score-compose locally to run and test their workload on Docker Compose
  • Once local development is complete, the changes are pushed to the repo and a CI workflow deploys to the target environment via the Platform Orchestrator using the humctl CLI
  • Advanced environment progression can be handled using the workload artefact API and Artefact Automation Pipelines

The CI/CD integration guide goes into more detail on these options.

Managed by Score

To prevent accidental manual modifications in the Humanitec UI, humctl and workload artefacts automatically add the humanitec.io/managed-by annotation to managed workloads. The optional humanitec.io/workload-source annotation can capture the source of the Score workload and can be set in the metadata annotations:

metadata:
  name: my-workload
  annotations:
    humanitec.io/workload-source: https://github.com/org/repo

The value will be turned into a link inside the Humanitec UI and allows developers to quickly jump to the source of the respective Score file.

The humctl score deploy command supports an optional --workload-source-url flag to override this. If you are using GitHub Actions, your humctl usage could look like:

humctl score deploy \
  ...
  -f score.yaml \
  --workload-source-url "https://github.com/${{ github.repository }}/blob/${{ github.ref_name }}/score.yaml"

Get started

Use these resources to get started with Score and the Humanitec tools:

  • The Five-minute IDP basic Score to showcase a full deployment round-trip
  • The Quickstart guide explores some more variations on using Score
  • The Score examples show how to configure a vast array of workload properties using Score

Examples