Score Specification reference
7 minute read
Score Specification definitions
The Score Specification is a YAML file that contains the following top-level reference definitions.
Use these definitions to describe a single Workload.
- Workload definition: (required) defines the metadata and
apiVersion
. containers
: (required) defines how the Workload’s tasks are executed.resources
: (optional) defines dependencies needed by the Workload.service
: (optional) defines how an application can expose its resources when executed.
Workload definition
Describes the Score Specification API version and metadata. Data in the metadata section can be referenced throughout other parts of the specification as well, for example ${metadata.name}
.
apiVersion: string
metadata:
name: string
apiVersion
: the declared Score Specification version.
- Valid options:
score.dev/v1b1
metadata
: the metadata description of your Workload.
name
: specifies a string that can describe your Workload.
You can reference any information available in the metadata section too.
Workload example
The following is a top level description for a Workload.
apiVersion: score.dev/v1b1
metadata:
name: hello-world
service:
ports:
# . . .
containers:
my-container:
# . . .
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 Score implementation (CLI) to resolve the resource by name, type, or any other meta information available.
Resources
resources:
[resource-name]:
metadata: # optional
annotations: # optional
[annotation-name]: [value]
type: [resource-type]
resources
: defines dependencies needed by the Workload.
resource-name
: a required property that specifies the resource name.
- Type: string.
- Constraints: alphanumeric string.
metadata
: an optional property that specifies additional resource metadata.
Type
: object.annotations
: an optional property that specifies metadata annotations.Type
: object.Constraints
: alphanumeric string key-value pairs.
resource-type
: specifies the resource in the target environment.
- Type: string.
- Constraints: alphanumeric string.
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 |
score-humanitec |
---|---|---|
environment |
Translates to the environment variables references. For example: ${PROPERTY-NAME} . |
Translates to the application values references. For example: ${values.property-name} . |
volume |
Translates into a reference to the external volume. This reference is usually used in a container’s volume mount specification. | Translates into a reference to the external volume. This reference is usually used in a container’s volume mount specification. |
service |
N/A | Translates to the module properties references. |
workload |
N/A | Reserved resource type. Its usage may lead to compatibility issues with future releases of score-humanitec. |
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.
The following Score file contains a single resource.
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
.
service:
ports:
port-name: string # (required)
port: integer # (required)
protocol: string # (optional)
hostIP: integer # (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:
SCTP
|TCP
|UDP
hostIP
: describes the host IP to bind to.
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.
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.
image: string
command: []string
args: []string
variables: map[string]string
files:
target: string
mode: string
content: []string
volumes:
source: string
path: string
target: string
read_only: [true | false]
resources:
limits: map[string]interface{}
requests: map[string]interface{}
livenessProbe: ContainerProbeSpec
httpGet:
path: string
port: int
httpHeaders:
name: string
value: string
readinessProbe:
httpGet:
scheme: string
path: string
port: int
httpHeaders:
name: string
value: string
container-id
: specifies a name of the container image.
image
: image name or tag.
command
: overrides image entry point.
args
: overrides entry point arguments.
variables
: specifies environment variables.
files
: specifies extra files to mount.
target
: specifies a path and name.mode
: specifies access mode.content
: specifies inline content and supports templates.
volumes
: specifies volumes to mount.
source
: specifies external volume reference.path
specifies a sub path in the volume.target
: specifies a target mount on the container.read_only
: if true, mounts as read only.
limits
: maximum allowed CPU memory.
memory
: a string value representing the maximum allowed CPU memory.cpu
: a string value representing the maximum allowed CPU.
requests
: minimum required CPU memory.
memory
: a string value representing the minimum required CPU memory.cpu
: a string value representing the minimum required CPU.
livenessProbe
: indicates if the container is running.
-
scheme
: specifies the identifier used for connecting to the host.- Defaults:
HTTP
- Valid values:
HTTP
|HTTPS
- Defaults:
-
httpGet
: performs an HTTPGet
on a specified path and port.path
: specifies a path for the HTTPGet
method.port
: specifies a port for the HTTPGet
method.
readinessProbe
: indicates if the container is ready to respond to requests.
-
scheme
: specifies the identifier used for connecting to the host.- Defaults:
HTTP
- Valid values:
HTTP
|HTTPS
- Defaults:
-
httpGet
: performs an HTTPGet
on a specified path and port.-
path
: specifies a path for the HTTPGet
method. -
port
: specifies a port for the HTTPGet
method. -
httpHeaders
: headers to set in the request. Allows repeated headers.name
: custom header to set in the request.value
: specifies a value.
-
Container example
The following example creates a container with the busybox
image.
containers:
container-id:
image: busybox # Docker image name and tag
command: # (Optional) Overrides image entry point
- "/bin/echo"
args: # (Optional) Overrides entry point point
- "Hello $(FRIEND)"
variables: # (Optional) Specifies environment variable
FRIEND: World!
files: # (Optional) Specifies extra files to mount
- target: /etc/hello-world/config.yaml # - Target file path and name
mode: "666" # - Access mode
content: # - Inline content (supports templates)
- "---"
- ${resources.env.APP_CONFIG}
volumes: # (Optional) Specifies volumes to mount
- source: ${resources.data} # - External volume reference
path: sub/path # - (Optional) Sub path in the volume
target: /mnt/data # - Target mount path on the container
read_only: true # - (Optional) Mount as read-only
resources: # (Optional) CPU and memory resources needed
limits: # - (Optional) Maximum allowed
memory: "128Mi"
cpu: "500m"
requests: # - (Optional) Minimal required
memory: "64Mi"
cpu: "250m"
livenessProbe: # (Optional) Liveness probe
httpGet: # - Only HTTP GET is supported
scheme: http # - Specify the schema (http or https)
path: /alive
port: 8080
readinessProbe: # (Optional) Readiness probe
httpGet: # - Only HTTP GET is supported
scheme: http # - Specify the schema (http or https)
path: /ready
port: 8080
httpHeaders: # - (Optional) HTTP Headers to include
- name: Custom-Header
value: Awesome