Overview

What are Workload Profiles?

Workload Profiles define how the Platform Orchestrator should convert a Workload specification into runtime artifacts, which in the Kubernetes context are Kubernetes manifests.

They do this by accepting a set of inputs derived from a Workload specification, mapping them out, and then using a Helm chart in the background to generate the Kubernetes manifests from them.

Each time a Workload is deployed via the Platform Orchestrator, a Workload Profile is always used, even if you might not be aware of it.

The Workload Profile being used effectively determines what you can specify in your Score and Score extension file.

By default, a Workload deployment uses the Profile called default-module, one of the built-in Workflow profiles. To see which properties it allows you to specify, go here.

And if those properties are all you need to achieve the desired result, you do not need to dive into Workload Profiles at all. It is when you want to go beyond the standard capabilities that you might want to choose a different Workload Profile, or create your own. Read on to learn about the background and how to find the solution that fits your needs.

What Workload Profiles do

A Workload Profile can expose any attribute of the Kubernetes API, like

Compute resources - CPU, memory, GPUs
Storage - disks, volumes
Networking - subnets, routes
Runtimes - languages, frameworks, containers
Dependencies - databases, caches, queues

By exposing certain attributes, and pre-defining others, Workload Profiles strike a balance between simplification and control. They shield developers from unwanted complexity and are therefore a powerful way to enable self-service.

How Workload Profiles work

A Workload Profile consists of these two parts:

A specification that defines the accepted inputs.
A Helm chart that transforms those inputs into Kubernetes resources.

The Helm chart’s values are exposed as inputs through the Workload Profile.

The Workload Profile is part of a transformation process that starts out with a Score file being deployed via the humctl CLI. The process performs these steps:

The humctl CLI is invoked via humctl score deploy -f score.yaml ...
- An optional Humanitec extension file is provided via the --extensions flag.
- The humctl CLI creates a Deployment Set from the combination of both files. The Deployment Set specifies the Workload Profile to use as well as all other inputs from the files. (Technically, the CLI generates a Delta, not a Set, to be able to alter existing Deployments. The handling is identical.)
The humctl CLI posts the Deployment Set to the Platform Orchestrator. The Platform Orchestrator uses the specified Workload Profile and maps the Deployment Set properties to the Workload Profile properties of the same name.
The Platform Orchestrator maps Workload Profile properties to Helm chart values of the same name.
The Platform Orchestrator uses the Helm chart named in the Deployment Set to generate Kubernetes manifests, and applies all manifests to the target cluster.

---
title: Transformation Process from Score to K8s manifests
---
%%{ init: {'flowchart': { 'curve': 'step' } } }%%
flowchart LR
  subgraph inputFiles[ ]
    subgraph scoreFile[Score File]
        scoreFileContent(containers: ...<br/>service: ...):::codeComponent
    end
    subgraph humanitecExtensionFile[Humanitec extension file]
        humanitecExtensionFileContent(labels...):::codeComponent
    end
  end
  inputFiles -->|1. humctl score deploy<br/>generates<br/>Deployment Set| deploymentSetContent
  scoreFile ~~~ humanitecExtensionFile
  subgraph deploymentSet[Deployment Set]
    deploymentSetContent(profile: default-module<br/>spec:<br/>&nbsp;&nbsp;containers: ...<br/>&nbsp;&nbsp;labels: ...<br/>&nbsp;&nbsp;service: ...):::codeComponent
  end
  subgraph workloadProfile[Workload Profile &quot;default-module&quot;]
    wpProperties(Properties):::components -->|3. Map<br/>values| wpChart(Helm Chart):::components
  end
  subgraph k8sManifests[K8s Manifests]
    k8sDeployment(Deployment<br/>with labels):::components
    k8sService(Service):::components
  end
  deploymentSetContent -->|2. Post to<br/>Platform<br/>Orchestrator| wpProperties
  wpChart -->|4. Apply| k8sDeployment
  wpChart -->|4. Apply| k8sService

  classDef codeComponent font-family:Courier,text-align:left
  classDef invisible fill:#00000000,stroke:#00000000
  class inputFiles invisible

All those transformations are performed automatically so that the Developer Workflow remains quite simple:

---
title: Workload Profiles
---
sequenceDiagram
  participant User
  participant Humanitec as Platform Orchestrator
  User->>Humanitec: Deploy a set of Workloads
  Humanitec->>Humanitec: Generates the k8s resources using the Workload Profile and Workload Profile Chart Version (Helm chart)
  participant K8s as Customer K8s cluster
  Humanitec->>K8s: Applies the k8s resources
  Humanitec->>User: Reports the status of the deploy

Built-in Workload Profiles

The Platform Orchestrator comes with three built-in Workload Profiles, allowing you to deploy a Workload as one of these Kubernetes Workload Resource types.

As a Deployment : default-module
As a Job : default-job
As a CronJob : default-cronjob

When deploying a Score file using the humctl Humanitec CLI, the CLI by default assigns the default-module Workload Profile in the output it generates, so your Workload will be installed as a Kubernetes Deployment. To override this behavior, you can provide a Score extension file specifying the Workload Profile you wish to use instead. See the next section for details.

How to use a specific Workload Profile

The humctl score deploy CLI command will produce a Deployment Delta specifying the Workload Profile humanitec/default-module by default. To override this behavior, create a Score Score extension file specifying the Workload Profile to use instead, like this:

cat << EOF > humanitec.score.yaml
apiVersion: humanitec.org/v1b1
profile: humanitec/default-cronjob
EOF

Then, specify this extension file when deploying your Score file using the --extensions flag.

humctl score deploy \
  --org my-org \
  --app my-app \
  --env development \
  --token $HUMANITEC_TOKEN \
  -f score.yaml \
  --extensions humanitec.score.yaml

How to select the right Workload Profile

Decision tree for selecting the Workload Profile

When selecting the right Workload Profile for your needs, consider these aspects:

What type of Kubernetes Workload Resource do you wish to create?
For the types covered by the built-in default-* Workload Profiles, is the built-in Profile sufficient?

Every Workload has unique requirements, so use the recommendation from this flowchart as a starting point. Then perform a more detailed evaluation.

---
title: Workload Profiles Decision Tree
---
%%{ init: {'flowchart': { 'curve': 'bumpX' } } }%%
flowchart LR
  %% The subgraphs serve to arrange the items vertically aligned despite a LR flow.
  %% They are rendered invisible through styling.
  subgraph col1[ ]
    start(START) --> k8sWorkloadResource(Kubernetes<br/>Workload Resource<br/>type?):::components
  end
  subgraph col2[ ]
    isDefaultModuleSufficient("Is<br/>&quot;default-module&quot;<br/>sufficient?"):::components
    isDefaultJobSufficient("Is<br/>&quot;default-job&quot;<br/>sufficient?"):::components
    isDefaultCronJobSufficient("Is<br/>&quot;default-cronjob&quot;<br/>sufficient?"):::components
  end
  subgraph col3[ ]
    doesScoreSpecSupportAllFeatures(Does the Score spec<br/>support all required properties?):::components
  end
  subgraph col4[ ]
    defaultModuleNoExtension[Workload Profile: &quot;default-module&quot;<br/>Score extension file: no]:::components
    defaultModuleExtension[Workload Profile: &quot;default-module&quot;<br/>Score extension file: yes]:::components
    defaultJob[Workload Profile: &quot;default-job&quot;<br/>Score extension file: yes]:::components
    defaultCronjob[Workload Profile: &quot;default-cronjob&quot;<br/>Score extension file: yes]:::components
    cwpf0[Workload Profile: Custom<br/>Score extension file: yes]:::components
    cwpf2[Workload Profile: Custom<br/>Score extension file: yes]:::components
    cwpf3[Workload Profile: Custom<br/>Score extension file: yes]:::components
    cwpf4[Workload Profile: Custom<br/>Score extension file: yes]:::components
  end
  k8sWorkloadResource -->|Deployment| isDefaultModuleSufficient
  k8sWorkloadResource -->|Job| isDefaultJobSufficient
  k8sWorkloadResource -->|CronJob| isDefaultCronJobSufficient
  isDefaultModuleSufficient -->|Yes| doesScoreSpecSupportAllFeatures
  doesScoreSpecSupportAllFeatures -->|Yes| defaultModuleNoExtension
  doesScoreSpecSupportAllFeatures -->|No| defaultModuleExtension
  isDefaultModuleSufficient -->|No| cwpf0
  isDefaultJobSufficient -->|Yes| defaultJob
  isDefaultJobSufficient -->|No| cwpf2
  isDefaultCronJobSufficient -->|Yes| defaultCronjob
  isDefaultCronJobSufficient -->|No| cwpf3
  k8sWorkloadResource -->|Other| cwpf4

  classDef columns fill:#00000000,stroke:#00000000
  classDef components font-family:Akkurat
  class col1,col2,col3,col4 columns
  linkStyle 0,1,2,3,4,5,6,7,8,9,10,11,12 stroke:#bbbbbb,font-family:Akkurat

Definitions

Sufficient: The Workload Profile contains all the properties you need, e.g. “annotations” or “service”. You can find instructions below on how to find and inspect available Workload Profiles.
Score spec: The official Score specification .
Extension file: Using this Workload Profile requires you to use a Score Score extension file specifying the profile as shown above.

Sample case: Deployment with labels

I want to deploy my Workload as a Kubernetes Deployment and set additional labels on this particular Workload.

Kubernetes Resource Type → Deployment.
Is default-module sufficient? → Yes. This built-in Workload Profile has “Labels” as one of its features.
Does the Score spec support all required features? → No. The Score specification cannot define Workload labels.
Are the Score extensions relevant for other Workloads? → No. I want to set labels on this Workload only.

→ You can use the default-module built-in Workload Profile and specify the label via a Score extension file. Find the example code below.

Sample case: CronJob with Annotation

I want to deploy my Workload as a Kubernetes CronJob and set an additional annotation on this Workload.

Kubernetes Resource Type → CronJob
Is default-cronjob sufficient? → Yes. This built-in Workload Profile has “Annotations’’ as one of its features.
Does the Score spec support all required features? → No. The Score specification can define annotations on resources, but not on Workloads.

→ You can use the default-job built-in Workload Profile and request its use via a Score extension file. That file will also have to contain the annotation.

Find the example code below.

Sample case: StatefulSet

I want to deploy my Workload as a Kubernetes StatefulSet .

Kubernetes Resource Type → Other

→ You need to create a Custom Workload Profile and request its use via a Score extension file. None of the built-in Workload Profiles produces a StatefulSet.

How to find and inspect available Workload Profiles

You may want to inspect an available Workload Profile to find out if it provides all of the properties you need to configure.

To see a list of all available Workload Profiles in your Organization, use this command:

humctl api get /orgs/${HUMANITEC_ORG}/workload-profiles \
  |  jq -r '.[] | .id'

curl -s https://api.humanitec.io/orgs/${HUMANITEC_ORG}/workload-profiles  \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" |  jq -r '.[] | .id'

This will output the IDs of both the built-in as well as any custom Workload Profiles your Organization might have.

To see the list of properties for any particular Workload Profile, use the following command. Replace “humanitec.default-cronjob” with the ID of the Workload Profile you want to inspect.

humctl api get /orgs/${HUMANITEC_ORG}/workload-profiles/humanitec.default-cronjob/versions/latest | \
  jq '{ properties: .spec_definition.properties }'

curl -s https://api.humanitec.io/orgs/${HUMANITEC_ORG}/workload-profiles/humanitec.default-cronjob/versions/latest \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" | \
  jq '{ properties: .spec_definition.properties }'

If a property has a "type": "feature", you can find details about it on the features page.

You can request additional features via Humanitec Support if you find that something essential is missing.

How to build the extension file

You need to provide a Score extension file to the humctl CLI in addition to the Score file whenever you need to do either or all of the following:

Request a Workload Profile other than the standard, which is default-module.
Provide inputs to the Workload Profile not covered by the Score specification.

The Workload Profile ID goes into the profile: property of the extension file like this:

apiVersion: humanitec.org/v1b1
profile: humanitec/default-cronjob

spec:
  ...

Any additional inputs (2.) go into the spec: section of the extension file. They must match the properties of the selected Workload Profile and will be merged into the Deployment Set generated by humctl, as shown above.

Switching the Workload Profile

Switching your Workload to a different Workload Profile than the one currently used is possible, even if the Workload has already been deployed. As long as the resulting Kubernetes resources, as generated by the bundled Helm chart, are named the same, they will be updated in-place with the next Deployment.

Any Kubernetes resources whose naming changes will be destroyed and recreated. Make sure to compare the Helm chart output of the currently and the newly used chart to prevent disruptions.

Examples

Execute all examples using the humctl Humanitec CLI, targeting a particular Application Environment like this:

humctl score deploy -f score.yaml \
  --org <my-org> \
  --app <my-app> \
  --env <my-env> \
  --token ${HUMANITEC_TOKEN} \
  --extensions humanitec.score.yaml

where HUMANITEC_TOKEN is an API token with Deployer rights into the Environment.

Example: Deployment with labels

To define a Kubernetes Deployment with additional labels , you can request the default-module built-in Workload Profile. It contains the “labels” Feature which lets you specify labels for the Deployment.

You prepare:

A regular Score file describing your Workload’s container.
A Score extension file requesting the labels. It does not need to specify the default-module Workload Profile as that is the default.

Score file Score extension file

Score file	Score extension file
`apiVersion: score.dev/v1b1 metadata: name: my-deployment containers: hello: image: busybox command: ["/bin/sh"] args: ["-c", "while true; do printenv; sleep 60; done"]`	`apiVersion: humanitec.org/v1b1 spec: labels: owner: pat department: accounting`

apiVersion: score.dev/v1b1

metadata:
  name: my-deployment

containers:
  hello:
    image: busybox
    command: ["/bin/sh"]
    args: ["-c", "while true; do printenv; sleep 60; done"]

apiVersion: humanitec.org/v1b1

spec:
  labels:
    owner: pat
    department: accounting

Variation: It may be that you wish to set the same label on a number of different Workloads. There are several ways to achieve this:

Provide the same Score extension file when deploying those Workloads.
Provide a Custom Workload Profile instead which has that label built into it. Then use a Score extension file specifying that Custom Workload Profile to be used.

Example: CronJob with Annotation

To define a Kubernetes CronJob which executes on a particular schedule, you can request the default-cronjob built-in Workload Profile. It contains the “schedules” Feature which lets you specify the schedule for the CronJob.

That Workload Profile also contains the “annotations” Feature.

You prepare:

A regular Score file describing your Workload’s container.
A Score extension file requesting the default-cronjob Workload Profile, specifying the annotation, and specifying the schedule(s) for that container.
The input format for the schedules in the extension file is defined through the Feature humanitec/schedules which the default-cronjob Workload Profile is using.

Score file Score extension file

Score file	Score extension file
`apiVersion: score.dev/v1b1 metadata: name: my-cronjob containers: ubuntu: image: ubuntu:latest`	`apiVersion: humanitec.org/v1b1 profile: humanitec/default-cronjob spec: annotations: owner: pat schedules: myschedule: containers: ubuntu: args: - "-c" - sleep 10 command: - /bin/bash schedule: "* * * * *"`

apiVersion: score.dev/v1b1

metadata:
  name: my-cronjob

containers:
  ubuntu:
    image: ubuntu:latest

apiVersion: humanitec.org/v1b1
profile: humanitec/default-cronjob

spec:
  annotations:
    owner: pat
  schedules:
    myschedule:
      containers:
        ubuntu:
          args:
            - "-c"
            - sleep 10
          command:
            - /bin/bash
      schedule: "* * * * *"

The Benefits of Workload Profiles

To sum it up, key benefits of Workload Profiles are:

Portable - can be used across environments and clusters
Composable - build new Workload Profiles by extending existing ones
Dynamic - parameters allow customization for each workload
Shareable - publish and reuse Workload Profiles across teams

With Workload Profiles, platform teams can define standardized application configurations and best practices once. Developers can then easily deploy their code using those proven Workload Profiles.

Workload Profiles abstract infrastructure details from developers and promote consistency and governance across environments.

FAQ

Do Workload Profiles handle Resources?

No. Score resources become externals in the Deployment Delta. These are handled by the Platform Orchestrator, but are not passed on into the Workload Profile.

Overview

What are Workload Profiles? #

What Workload Profiles do #

How Workload Profiles work #

Built-in Workload Profiles #

How to use a specific Workload Profile #

How to select the right Workload Profile #

Decision tree for selecting the Workload Profile #

Definitions #

Sample case: Deployment with labels #

Sample case: CronJob with Annotation #

Sample case: StatefulSet #

How to find and inspect available Workload Profiles #

How to build the extension file #

Switching the Workload Profile #

Examples #

Example: Deployment with labels #

Example: CronJob with Annotation #

The Benefits of Workload Profiles #

FAQ #

Do Workload Profiles handle Resources? #