## 1. Project Overview & Quickstart (score-spec/spec) [](https://opensource.org/licenses/Apache-2.0) [](CODE_OF_CONDUCT.md) [](https://github.com/score-spec/spec/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) ## The Score Specification Score is an open-source workload specification designed to simplify development for cloud-native developers. The specification enables you to describe your workload's configuration in a vendor-neutral way, eliminating the need for tooling-specific syntax from platforms such as Docker Compose or Kubernetes. By leveraging familiar concepts and semantics, defining a workload’s configuration becomes as simple as stating, “I want a database of type X and an event queue of type Y to accompany my workload”. Below is an example of a Score specification describing a web server that queries a Postgres database on each request. Typically, this file is saved alongside the workload's source code in version control. ```YAML # The version string helps identify the Score file syntax apiVersion: score.dev/v1b1 metadata: name: sample # A set of containers deployed together for this Workload. containers: main: # The "default" image for our service. When deploying, we may override this with a particular tag. image: ghcr.io/score-spec/sample-app-gif:sha-2533037 variables: # Pass the resource outputs to our container as environment variables. The Score implementation takes care of securing any secret access as needed. PG_CONNECTION_STRING: "postgresql://${resources.db.username}:${resources.db.password}@${resources.db.host}:${resources.db.port}/${resources.db.database}?sslmode=disable" # The service ports indicate which ports of the Workload are exposed for other services to call. service: ports: web: port: 8080 # Each resource dependency has a name and definition that helps the Score implementation link or provision the required resource. resources: db: # This database is specific to this Workload and not shared. type: postgres dns: # Ensure a dns name is available for request routing. type: dns route: # We want to ensure that requests on the Workload hostname go to our service port. type: route params: host: ${resources.dns.host} path: / port: 8080 ``` ### Key Features of Score Looking at the example above, you'll notice that the Score specification is: * **platform-agnostic**: Score is not tied to any specific platform or tool. It integrates seamlessly with Docker, Kubernetes, Helm, and other container orchestration platforms, allowing developers to define the Score spec once, independently of the target environments. * **environment-agnostic**: Score captures the configuration that remains consistent across all environments, effectively separating environment-agnostic from environment-specific configurations. For instance, the database connection string `PG_CONNECTION_STRING` in the example above is parameterized (i.e. described in an environment-agnostic way), allowing it to be resolved in each target environment with the appropriate credentials. * **tightly scoped**: Score describes workload-level properties. It does not intend to be a fully featured YAML replacement for any platform, thereby shielding developers from the complexity of container orchestration tools like Kubernetes. * **declarative**: With Score, developers declare what their workload requires to run as part of the Score specification. The platform in the target environment is responsible for resolving individual runtime requirements. This establishes a contract between dev and ops: If the requirements listed in the spec are honoured, the workload will run as intended. The current version of the specification schema is stored [here](./score-v1b1.json). For a more detailed specification reference, check out our [developer documentation](https://docs.score.dev/docs/score-specification/score-spec-reference/). ## Implementation of the Score Specification Once you define your workload's runtime requirements with the Score specification, a Score Implementation translates it into the desired target output format as illustrated in the graphic below. Currently, we offer two reference implementations: * [score-compose](https://github.com/score-spec/score-compose): Converts your Score specification into a `docker-compose.yaml` file. * [score-k8s](https://github.com/score-spec/score-k8s): Generates `manifests.yaml` files from your Score specification to deploy to a Kubernetes cluster. These implementations are suitable for practical use and serve as blueprints for creating custom implementations. If you're interested in building a Score implementation but need guidance, feel free to reach out — we're here to help! Community-built implementations are typically hosted and maintained by their creators. These can be referenced in our documentation or kept private. If a contributor wishes to donate their implementation to our project, we are open to exploring that option. ## Benefits of Score Score aims to reduce developer toil and cognitive load by only having to define a single specification file that works across multiple platforms. Cloud native developers often struggle with configuration inconsistencies between environments. This gets even more complicated when the technology stack in each environment is different. For example: What if you use Docker Compose for local development, but deploy to a Kubernetes-based development environment? Not only do you have to figure out Docker Compose and Kubernetes, but you need to keep them in sync. This results in various bottlenecks along the application delivery lifecycle: - Tech & tools that require specialized knowledge and operational expertise are imposed on developers. - Different configuration rules, constructs and values between local and remote environments increase the risk of configuration inconsistencies. - Keeping a multitude of platforms and environment-specific configuration files in sync leads to repetitive configuration work. Score provides a single, easy to understand specification for each workload that describes its runtime requirements in a declarative manner. The `score.yaml` file allows generating configuration in an automated, standardized and one directional way. By reducing the risk of incorrect or inconsistent configurations across environments, Score helps developers focus on their core tasks and enhances their day-to-day work experience. ## Get in touch Connect with us through the [Score](https://cloud-native.slack.com/archives/C07DN0D1UCW) channel in the CNCF Slack () or contact us via email at team@score.dev. We host regular community meetings to discuss updates, share ideas, and collaborate. Here are the details: | Community call | Info | |:-----------|:------------| | Meeting Link | Join via [Zoom](https://zoom-lfx.platform.linuxfoundation.org/meeting/98284206225?password=a09e77df-8c63-44ca-8a48-12de22fdffe4) or view the [Calendar](https://zoom-lfx.platform.linuxfoundation.org/meetings/score?view=month) | | Meeting Agenda & Notes | Add to our agenda or review minutes [here](https://github.com/score-spec/spec/discussions/categories/community-meetings) | | Meeting Time | 3:00-4:00 CET/CEST, every first Thursday of the month unless specified | If you can't attend at the scheduled time but would like to discuss something, please reach out. We’re happy to arrange an ad-hoc meeting that fits your schedule. ### Documentation You can find our documentation at [docs.score.dev](https://docs.score.dev/docs/). ### Roadmap See [Roadmap](roadmap.md). You can [submit an idea](https://github.com/score-spec/spec/issues/new) anytime. ### Contribution Guidelines and Governance Our general contributor guidelines can be found in [CONTRIBUTING.md](CONTRIBUTING.md). Please note that some repositories may have additional guidelines. For more information on our governance model, please refer to [GOVERNANCE.md](GOVERNANCE.md). ## 2. Official Technical Reference & Guides (score-spec/docs) [](https://github.com/score-spec/docs/actions/workflows/hugo.yml) [](https://github.com/score-spec/docs/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) ## Docs This section covers how to build the documentation site with Hugo. For information on Score's style guide see the [Style guide](styles/style-guide.md). ### Running the website locally #### `yarn` We use `yarn` (for MacOS: `brew install yarn`) as a package manager to ensure the versions of Hugo and associated tools are up to date. All commands that execute those tools are prefixed with `yarn run` or are aliased in the `package.json` file. To install the packages: ``` yarn install ``` To run the server locally: ``` yarn build OR yarn run hugo server ``` And then view it at . #### `score-compose` You can [install `score-compose`](https://docs.score.dev/docs/score-implementation/score-compose/installation/) and then build and run this hugo website as a container: ``` score-compose init --no-sample score-compose generate score.yaml --build main=. docker compose up --build -d curl $(score-compose resources get-outputs dns.default#score-docs.dns --format '{{ .host }}:8080/docs/') ``` ### Deployment This site is currently deployed through Github Pages with a CNAME directing `docs.score.dev` to `score-spec.github.io`. The DNS configuration is managed by Humanitec. ### Format docs The following section covers how to format and lint prose. ### Formatters and linters This project uses the [dprint](https://dprint.dev/overview/) to format documentation. dprint is a command line application that automatically formats code. Use `dprint` to format your documentation. ```bash yarn fmt ``` Example output. ```bash $ yarn fmt Formatted 1 file. ✨ Done in 0.13s. ``` This project uses the [Vale](https://vale.sh) with a [Vale-compatible implementation of the Google Developer Documentation Style Guide](https://github.com/errata-ai/Google). On MacOS, install it through `brew install vale`. For example, to lint a document run: ```bash vale sync vale styles/style-guide.md ``` Example output. ```bash styles/style-guide.md 40:71 error Did you really mean Vale.Spelling 'inclusivity'? ✖ 1 error, 0 warnings and 0 suggestions in 1 file. ``` To lint all documents, run `yarn lint`. ## Autogenerated content ### Score example hub This site uses content from external Git repositories to create and continuously update the "Score example hub" pages. The external repos are pulled in to the `/gen/external-content` folder. The commands for the initial integration of the repos are: ```bash git remote add -f -t main --no-tags examples https://github.com/score-spec/examples.git git remote add -f -t main --no-tags community-provisioners https://github.com/score-spec/community-provisioners.git git remote add -f -t main --no-tags score-compose https://github.com/score-spec/score-compose.git git remote add -f -t main --no-tags score-k8s https://github.com/score-spec/score-k8s.git git remote add -f -t main --no-tags patch-templates https://github.com/score-spec/community-patchers.git git read-tree --prefix=gen/external-content/score/specification -u examples/main:specification git read-tree --prefix=gen/external-content/resource-provisioners/default/score-compose -u score-compose/main:internal/command git read-tree --prefix=gen/external-content/score/resources/default-provisioners -u examples/main:resources git read-tree --prefix=gen/external-content/score/resources/community-provisioners -u community-provisioners/main git read-tree --prefix=gen/external-content/resource-provisioners/default/score-k8s -u score-k8s/main:internal/provisioners/default git read-tree --prefix=gen/external-content/resource-provisioners/community -u community-provisioners/main git read-tree --prefix=gen/external-content/patch-templates -u patch-templates/main git add gen/external-content git commit -s -S -m "Integrating external content" ``` These commands will not have to be repeated unless re-creating the repo integration, or moving the source location. In that case, remove the `remote`, delete the local contents, repeat these commands targeting the new location, and update the generation scripts. To generate the example hub pages based on the external content, execute this command: ```bash yarn gen-example-pages ``` ### Pulling new content To pull the current content from the remote example library repo, execute this command: ```bash yarn gen-get-external-content ``` Refer to the [package.json`](./package.json) to see the actual implementation of this command. ## Troubleshooting documentation site builds This section covers common build issues with Hugo. ### Failed to resolve output format `print` When building the server, you may receive the following error message. ```bash Error: from config: failed to resolve output format "print" from site config error Command failed with exit code 255. info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command. ``` To resolve this issue, delete the temporary Hugo cache directory. By default, [`-cacheDir`](https://gohugo.io/commands/hugo_server/) is stored at `$TMPDIR/hugo_cache`. ```bash rm -rf $TMPDIR/hugo_cache ``` ### `package-lock.json` locked files When running `yarn`, you may receive the following error message. ```bash warning package-lock.json found. Your project contains lock files generated by tools other than Yarn. It is advised not to mix package managers in order to avoid resolution inconsistencies caused by unsynchronized lock files. To clear this warning, remove package-lock.json. ``` To resolve this issue, delete the `package-lock.json` file. ```bash rm package-lock.json ``` You can find our documentation at [docs.score.dev](https://docs.score.dev/docs/). ### Contribute If you have a suggestion to improve our documentation, please fork the repo and create a pull request. You can also open an issue with the tag `enhancement`. 1. Fork the Project. 2. Create your Feature Branch. `git checkout -b feature/feature-name` 3. Commit your Changes. `git commit -s -m "Add some amazing documentation enhancement"` 4. Push to the Branch. `git push origin feature/feature-name` 5. Open a Pull Request. Read [CONTRIBUTING](CONTRIBUTING.md) for more information. ### Roadmap See [Roadmap](roadmap.md). You can [submit an idea](https://github.com/score-spec/spec/issues/new) anytime. ### License [](https://opensource.org/licenses/Apache-2.0) ### Code of conduct [](CODE_OF_CONDUCT.md)