From 47b9e119383b3de824b9a47323d4fc37e892920b Mon Sep 17 00:00:00 2001 From: Ben Meier Date: Tue, 29 Oct 2024 16:28:38 +0000 Subject: [PATCH] chore: added example of the resource id reference form Signed-off-by: Ben Meier --- .../score-spec-reference.md | 30 ++++++++++++++++--- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/content/en/docs/score specification/score-spec-reference.md b/content/en/docs/score specification/score-spec-reference.md index 45053ca..47fca78 100644 --- a/content/en/docs/score specification/score-spec-reference.md +++ b/content/en/docs/score specification/score-spec-reference.md @@ -125,19 +125,19 @@ containers: `args`: if specified, overrides the arguments passed to the container entrypoint. -`variables`: the environment variables for the container. Container variables support both metadata and resource output placeholders. +`variables`: the environment variables for the container. Container variables support both metadata and resource output [placeholders]({{ relref . "#placeholder-references" }}). `files`: the extra files to mount into the container. Either `content` or `source` must be specified along with `target`. - `target`: the file path to expose in the container. - `mode`: the optional file access mode in octal encoding. For example 0600. -- `source`: the relative or absolute path to the content file. File content supports both metadata and resource output placeholders unless `noExpand` is true. -- `content`: the inline content for the file. File content supports both metadata and resource output placeholders unless `noExpand` is true. +- `source`: the relative or absolute path to the content file. File content supports both metadata and resource output [placeholders]({{ relref . "#placeholder-references" }}) unless `noExpand` is true. +- `content`: the inline content for the file. File content supports both metadata and resource output [placeholders]({{ relref . "#placeholder-references" }}) unless `noExpand` is true. - `noExpand`: if set to true, the placeholders expansion will not occur in the contents of the file. `volumes`: the volumes to mount. -- `source`: the external volume reference. The volume source supports resource output placeholders. +- `source`: the external volume reference. The volume source supports resource output [placeholders]({{ relref . "#placeholder-references" }}). - `path`: an optional sub path in the volume. - `target`: the target mount on the container. - `readOnly`: indicates if the volume should be mounted in a read-only mode. @@ -330,6 +330,7 @@ In general, the Score specification does not specify a set of supported `resourc - `environment`: This resource type is a source of environment specific values. In `score-compose` this comes from environment variables present when running `score-compose generate`, in Humanitec this comes from the deployed environment configuration. In `score-k8s` this has no specific meaning. - `volume`: This resource type should be used with the container volume source field. This is generally implementation specific due to the varied behavior and configuration of mounted volumes. +- `service`: This resource type is used in Humanitec to return service placeholders. It has no specific meaning in `score-compose` or `score-k8s`. ## Placeholder References @@ -402,6 +403,27 @@ At deploy time resources are evaluated first as an acyclic graph: first `some-re As a practical example, a resource of type `postgres` may have outputs like `host`, `port`, `username`, and `password` which we may pass to the Workload variables or to a related resource to consume. +### Resource id references + +The `${resources.name}` reference format will return a unique resource id for the named resource. This is rarely used, but is most frequently used for historical reasons in the container volumes `source` field which links the container to a resource dependency. The Score implementation is responsible for validating this reference and returning the resource in a form that allows the volume to be mounted. + +For example: + +```yaml +apiVersion: score.dev/v1b1 +metadata: + name: my-workload +containers: + example: + image: some-image + volumes: + - source: ${resources.my-volume} + target: /mnt/volume +resources: + my-volume: + type: volume +``` + ### Supporting secret or sensitive resource outputs Some resources may return outputs that are expected to be secret and not stored or interpolated as plaintext. For example, a database password should be kept as a secret where possible.