Score Extensions file

What is a Score Extension File?

Score is deliberately platform agnostic. Therefore the Score Specification only covers features that are broadly applicable across the vast majority of container runtimes/platforms. It is sometimes the case that Developers and Platform Engineers need to have greater control over how workloads are configured in Kubernetes. The Humanitec Platform Orchestrator provides 2 main ways of doing this:

  • the workload resource type which allows Platform Engineers to modify the workload at deployment time and
  • the Humanitec Score Extension file which allows Developers to configure elements of the Kubernetes workload.

The Humanitec Score Extension file is intended to sit in the source code repository of the workload next to the Score file. By convention the file is named humanitec.score.yaml. It extends what Score is capable of - specifically exposing additional features and functionality of the Platform Orchestrator and Kubernetes.

Example #

A common usecase for a Score Extension file is to add annotations to a pod. This can be done with the Humanitec Score Extensions file would look as follows:

humanitec.score.yaml

apiVersion: humanitec.org/v1b1

spec:
  pod:
    annotations:
      billing-code: MyBilling-CODE

This could be included in a deployment using humctl as follows:

humctl score deploy \
              -f score.yaml \
              --extensions humanitec.score.yaml \
              --app ${APP_ID} \
              --env ${ENV_ID} \
              --org ${HUMANITEC_ORG}

Extensions file structure

The Humanitec Score Extensions file actually represents a module section within a Humanitec Deployment Set . It has the following top level properties:

Property Type Description
apiVersion string Must be set to humanitec.org/v1b1. Indicates this is a Humanitec Score Extension file.
deploy map Additional configuration defining how the workload should be deployed.
profile string The Workload Profile to use for the workload. (defaults to humanitec/default-module)
spec map Additional properties which are merged into the Workload Profile .

All properties except apiVersion are optional.

deploy property

The deploy property is an object used to provide extra control around how the workload is deployed.

The success can be used to define what a successful deployment of the workload means. By default, a successful deployment is just successfully updating the manifests in the cluster. For long running workloads such as Kubernetes Deployments or StatefulSets success can be when the workload reports “ready” via its Rediness probe. For Kubernetes Job workloads, the deployment can be marked successful once the Job has completed successfully.

The object has the following properties:

Property Type Default Description
success string deploy Can be one of deploy (manifests are in the cluster), available (manifests are in cluster and readiness check is successful) or complete (only make sense for Job workloads - success is the job completes successfully).
timeout integer 300 Time in seconds to wait for the deployment of the workload to complete. Usually used with success set to available or complete.
when string deploy Can be one of before deploy or after, specifying the phase in which the workload should be deployed relative the main deployment.

profile property

The profile property defines the Workload Profile to use. The workload profile affects what can be added to the spec part of the extensions file.

By default, this property will be humanitec/default-module.

spec property

The spec property holds an object which will be merged into the Deployment Set along with what is generated from the Score file. The allowable contents of the spec section are defined by the Workload Profile Features supported by the workload profile defined in the profile property.

Example

This extension file demonstrates how a job that should be configured to run before the rest of the deployment could be configured with a Score Extension File.

apiVersion: humanitec.org/v1b1

# Run the job before the main deployment, waiting for the job to complete
# before moving to the main deployment. If the job runs for longer than
# 120 seconds, it will mark the deployment as a failure.
deploy:
  success: complete
  timeout: 120
  when: before

# Use the Humanitec provided Worlkload profile for a Kubernetes Job
profile: humanitec/default-job

spec:
  # Add the ttlSecondsAfterFinished and backoffLimit properties to the
  # JobSpec object in Kubernetes.
  job:
    backoffLimit: 2
    ttlSecondsAfterFinished: 30

  # Add a annotation to the PodTemplate within the JobSpec
  pod:
    annotations:
      billing-code: MyBilling-CODE

Overview

Examples