From dd6e2964ca9d00dfd4ed1b58ecde396d479b7563 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Susa=20T=C3=BCnker?= Date: Tue, 16 Apr 2024 13:21:43 +0200 Subject: [PATCH 1/2] Fixed broken image link and inconsistent page structure --- .../ide-linter-autocomplete.md | 2 +- .../score-spec-reference.md | 276 +++++++++--------- ...nting.png => vsc-score-schema-linting.png} | Bin 3 files changed, 139 insertions(+), 139 deletions(-) rename static/images/{VSC Score schema linting.png => vsc-score-schema-linting.png} (100%) diff --git a/content/en/docs/score specification/ide-linter-autocomplete.md b/content/en/docs/score specification/ide-linter-autocomplete.md index 945d91e0..efa43c7d 100644 --- a/content/en/docs/score specification/ide-linter-autocomplete.md +++ b/content/en/docs/score specification/ide-linter-autocomplete.md @@ -31,5 +31,5 @@ For instance, configuring Visual Studio Code (VSC) involves the following steps: For reference: -![VSC instructions](/static/images/VSC%20Score%20schema%20linting.png) +![VSC instructions](/images/vsc-score-schema-linting.png) diff --git a/content/en/docs/score specification/score-spec-reference.md b/content/en/docs/score specification/score-spec-reference.md index f4cd0fcb..f8aa9824 100644 --- a/content/en/docs/score specification/score-spec-reference.md +++ b/content/en/docs/score specification/score-spec-reference.md @@ -17,9 +17,9 @@ The Score Specification is a YAML file that contains the following top-level ref Use these definitions to describe a single Workload. - [Workload definition](#workload-definition): (required) defines the metadata and `apiVersion`. -- [`containers`](#container-definition): (required) defines how the Workload's tasks are executed. -- [`resources`](#resources-definition): (optional) defines dependencies needed by the Workload. -- [`service`](#service-definition): (optional) defines how an application can expose its resources when executed. +- [containers](#container-definition): (required) defines how the Workload's tasks are executed. +- [resources](#resources-definition): (optional) defines dependencies needed by the Workload. +- [service](#service-definition): (optional) defines how an application can expose its resources when executed. ## Workload definition @@ -61,141 +61,6 @@ resources: env: # . . . ``` - -## Resources definition - -The Resource section of the Score Specification allows users to describe the relationship between Workloads and their dependent resources in an environment-agnostic way. The purpose of the Resource section is to validate resource references in the same Score file. - -Resources can be anything and Score doesn't differentiate resources by types. The resource section can be used to provision multiservice setups with platforms like Docker Compose. - -It is up to the Score implementation (CLI) to resolve the resource by name, type, or any other meta information available. - -### Resources - -```yaml -resources: - [resource-name]: - metadata: # optional - annotations: # optional - [annotation-name]: [value] - type: [resource-type] - class: [resource-class] -``` - -**`resources`**: defines dependencies needed by the Workload. - -**`resource-name`**: a required property that specifies the resource name. - -- **Type**: string. -- **Constraints**: alphanumeric characters and dashes "-". - -**`metadata`**: an optional property that specifies additional resource metadata. - -- **`Type`**: object. - - **`annotations`**: An optional property to specify meta data for a resource. This can be utilised to provide additional instructions for the Score CLI Implementation to interpret. - - **`Type`**: object. - - **`Constraints`**: key-value pairs with alphanumeric characters and dashes "-". - -`type`: specifies the resource type. - -- **Type**: string. -- **Constraints**: alphanumeric characters and dashes "-". - -`class`: a specialisation of the resource type. For example, a workload that needs an externally accessible storage bucket might set the class to external while the workload that requires an encrypted resource might have a class of sensitive. - -- **Type**: string. -- **Constraints**: alphanumeric characters and dashes "-". - -### Reserved resource types - -In general, `resource-type` has no meaning for Score, but it can affect how the targeted Score implementation tool resolves the resource. The following conventions are _reserved_ resource types. - -| Resource type | `score-compose` | -| ------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `environment` | Translates to the environment variables references. For example: `${PROPERTY-NAME}`. | -| `volume` | Translates into a reference to the external volume. This reference is usually used in a container’s volume mount specification. | -| `service` | N/A | -| `workload` | N/A | - -### Referencing resources - -Resources declared in the resources section of a Score file can be used in substitution patterns in different places. - -### Resource example - -The Score implementation (CLI) resolves resource references and performs value substitution in a specific manner. - -For example, when using the `score-compose` command, resource references within substitution patterns are replaced with corresponding environment variable references in the resulting `compose.yaml` configuration file. To gather all the required environment variables, you can utilize the `--env-file` command line parameter to generate a reference `.env` file. This file can be populated with the necessary values by the user. -For more instructions, see to the [.env file documentation](https://docs.docker.com/compose/environment-variables/#the-env-file). - -The following Score file contains a single resource. - -```yaml -apiVersion: score.dev/v1b1 - -metadata: - name: backend - -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} - -resources: - db: - type: postgres -``` - -## Service definition - -A `service` contains one or more networks ports that can be exposed to external applications. - -The `port` specification can include `public port` and should include `container port`. - -```yaml -service: - ports: - port-name: string # (required) - port: integer # (required) - protocol: string # (optional) - targetPort: integer # (optional) -``` - -`port-name`: describes the name of the port. - -`port`: contains the port to expose to an external application. - -`protocol`: describes the transportation layer protocol. - -- Defaults: `TCP` -- Valid values: `TCP` | `UDP` - -`targetPort`: describes the port to expose on the host. If the `targetPort` isn't specified, then it defaults to the required `port` property in the container. - -### Service example - -The following example advertises two public ports `80`, which points to the container's port `8080`, and `8080`, which also points to the container's port. - -```yaml -apiVersion: score.dev/v1b1 - -metadata: - name: web-app - -service: - ports: - www: - port: 80 - targetPort: 8080 - admin: - port: 8080 - protocol: UDP -# . . . -``` - ## Container definition The Workload container’s specification describes how the Workload's tasks are executed. @@ -347,3 +212,138 @@ containers: - name: Custom-Header value: Awesome ``` + +## Resources definition + +The Resource section of the Score Specification allows users to describe the relationship between Workloads and their dependent resources in an environment-agnostic way. The purpose of the Resource section is to validate resource references in the same Score file. + +Resources can be anything and Score doesn't differentiate resources by types. The resource section can be used to provision multiservice setups with platforms like Docker Compose. + +It is up to the Score implementation (CLI) to resolve the resource by name, type, or any other meta information available. + +### Resources + +```yaml +resources: + [resource-name]: + metadata: # optional + annotations: # optional + [annotation-name]: [value] + type: [resource-type] + class: [resource-class] +``` + +**`resources`**: defines dependencies needed by the Workload. + +**`resource-name`**: a required property that specifies the resource name. + +- **Type**: string. +- **Constraints**: alphanumeric characters and dashes "-". + +**`metadata`**: an optional property that specifies additional resource metadata. + +- **`Type`**: object. + - **`annotations`**: An optional property to specify meta data for a resource. This can be utilised to provide additional instructions for the Score CLI Implementation to interpret. + - **`Type`**: object. + - **`Constraints`**: key-value pairs with alphanumeric characters and dashes "-". + +`type`: specifies the resource type. + +- **Type**: string. +- **Constraints**: alphanumeric characters and dashes "-". + +`class`: a specialisation of the resource type. For example, a workload that needs an externally accessible storage bucket might set the class to external while the workload that requires an encrypted resource might have a class of sensitive. + +- **Type**: string. +- **Constraints**: alphanumeric characters and dashes "-". + +### Reserved resource types + +In general, `resource-type` has no meaning for Score, but it can affect how the targeted Score implementation tool resolves the resource. The following conventions are _reserved_ resource types. + +| Resource type | `score-compose` | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `environment` | Translates to the environment variables references. For example: `${PROPERTY-NAME}`. | +| `volume` | Translates into a reference to the external volume. This reference is usually used in a container’s volume mount specification. | +| `service` | N/A | +| `workload` | N/A | + +### Referencing resources + +Resources declared in the resources section of a Score file can be used in substitution patterns in different places. + +### Resource example + +The Score implementation (CLI) resolves resource references and performs value substitution in a specific manner. + +For example, when using the `score-compose` command, resource references within substitution patterns are replaced with corresponding environment variable references in the resulting `compose.yaml` configuration file. To gather all the required environment variables, you can utilize the `--env-file` command line parameter to generate a reference `.env` file. This file can be populated with the necessary values by the user. +For more instructions, see to the [.env file documentation](https://docs.docker.com/compose/environment-variables/#the-env-file). + +The following Score file contains a single resource. + +```yaml +apiVersion: score.dev/v1b1 + +metadata: + name: backend + +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} + +resources: + db: + type: postgres +``` + +## Service definition + +A `service` contains one or more networks ports that can be exposed to external applications. + +The `port` specification can include `public port` and should include `container port`. + +```yaml +service: + ports: + port-name: string # (required) + port: integer # (required) + protocol: string # (optional) + targetPort: integer # (optional) +``` + +`port-name`: describes the name of the port. + +`port`: contains the port to expose to an external application. + +`protocol`: describes the transportation layer protocol. + +- Defaults: `TCP` +- Valid values: `TCP` | `UDP` + +`targetPort`: describes the port to expose on the host. If the `targetPort` isn't specified, then it defaults to the required `port` property in the container. + +### Service example + +The following example advertises two public ports `80`, which points to the container's port `8080`, and `8080`, which also points to the container's port. + +```yaml +apiVersion: score.dev/v1b1 + +metadata: + name: web-app + +service: + ports: + www: + port: 80 + targetPort: 8080 + admin: + port: 8080 + protocol: UDP +# . . . +``` + diff --git a/static/images/VSC Score schema linting.png b/static/images/vsc-score-schema-linting.png similarity index 100% rename from static/images/VSC Score schema linting.png rename to static/images/vsc-score-schema-linting.png From 9a2c4e3b29ff2ca2ee75a9e905ae4b72b66b8fa3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Susa=20T=C3=BCnker?= Date: Tue, 16 Apr 2024 13:32:01 +0200 Subject: [PATCH 2/2] Updated GitHub actions instructions --- content/en/docs/How to/github.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/content/en/docs/How to/github.md b/content/en/docs/How to/github.md index 508e7060..51e398eb 100644 --- a/content/en/docs/How to/github.md +++ b/content/en/docs/How to/github.md @@ -14,7 +14,7 @@ You can use any Score implementation CLI in your GitHub Action workflows, for ex The following is a guide to setting up the Score implementation CLI in your GitHub Action workflows. -For the Score GitHub Action, see [Setup Score](https://github.com/score-spec/setup-score) +For the Score GitHub Action, see [Setup Score](https://github.com/score-spec/setup-score). ## Usage @@ -24,8 +24,8 @@ To use the Score GitHub Action, add the following step to your [workflow](https: steps: - uses: score-spec/setup-score@v2 with: - file: score-compose - version: '0.6.0' + file: + version: '' - run: score-compose --version ``` @@ -33,8 +33,9 @@ This will download and cache the specified version of the `score-compose` CLI an The action accepts the following inputs: -- `file` - The Score CLI tool to install. For example, `score-humanitec`, `score-compose`, or `score-helm`. -- `version` - The version of the CLI to install. +- `file` - The Score CLI tool to install. For example `score-compose` or `score-helm`. + +- `version` - The version of the CLI to install. You can retrieve the latest version from the release page of the respective CLI tool you're working with. For example [score-compose releases](https://github.com/score-spec/score-compose/releases) or [score-helm releases](https://github.com/score-spec/score-helm/releases). ## Example @@ -53,10 +54,10 @@ jobs: - uses: score-spec/setup-score@v2 with: file: score-compose - version: '0.6.0' + version: '0.13.0' - run: score-compose --version ``` -This installs version `0.6.0` of `score-compose`, adds it to `$PATH`, and runs `score-compose --version` to verify it is set up correctly. +This installs version `0.13.0` of `score-compose`, adds it to `$PATH`, and runs `score-compose --version` to verify it is set up correctly. The action caches the Score binary, so it won't need to download it each run.