Custom Workload Profiles

What are Custom Workload Profiles?

In addition to the built-in Workload Profiles, you can also create completely custom Workload Profiles.

Custom Workload Profiles can be used to:

  • Customize the Workload edition experience inside the UI.
  • Expose any object of the Kubernetes API which you need to customize.
  • Customize how the Platform Orchestrator is using Kubernetes Objects.
  • Use Kubernetes Objects that aren’t supported by the built-in Workload Profiles, e.g. StatefulSets, Custom Resource Definitions (CRDs).

Just like the built-in Workload Profiles, a Custom Workload Profile consists of two parts:

  • A specification that defines the accepted input of your Workload Profile.
  • A Helm chart that translates the Deployment Set input into Kubernetes resources.

Once configured, a Custom Workload Profile can be used in the developer workflow just like any other Workload Profile, as shown in the Overview.

Within the Platform Orchestrator the lifecycle of a Workload Profile is managed using the following entities:

  • The Workload Profile itself, which can be referenced by a Workload.
    • The Workload and Workload Profile entities are loosely coupled. Workloads can reference non-existing Workload Profiles and this will cause a failure when deploying. You can also have unused Workload Profiles.
  • A Workload Profile Chart Version, which represents an uploaded Helm chart version.
    • When you create or update a Workload Profile, the Platform Orchestrator API ensures that the referenced Workload Profile Chart Version exists.

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

---
title: Workload Profiles
---
erDiagram
    ORG ||--o{ DEPLOYMENT_SET : contains
    DEPLOYMENT_SET }o--o{ WORKLOAD_PROFILE : references
    ORG ||--o{ WORKLOAD_PROFILE : contains
    WORKLOAD_PROFILE {
        string spec_definition
    }
    WORKLOAD_PROFILE ||--|{ WORKLOAD_PROFILE_CHART_VERSION : references
    ORG ||--o{ WORKLOAD_PROFILE_CHART_VERSION : contains
    WORKLOAD_PROFILE_CHART_VERSION {
        binary helm-chart
    }

Specification

A Workload Profile has the following properties:

  • id — the id to reference inside a Deployment Set as profile: profile-id.
  • description (optional) — describes the purpose of the Workload Profile.
  • deprecation_message (optional) — this can be set when the Workload Profile should be marked as deprecated. Deprecated Workload Profiles are omitted by default in the UI, but can still be used.
  • spec_definition — describes the expected Workload Profile input. Find more details and examples below.
  • version (optional) — defines a custom version string. The API doesn’t enforce any ordering and the latest update will always be the latest version.
  • workload_profile_chart — references a Workload Profile Chart Version. This can either be one of the built-in charts or a Custom Workload Profile Chart. Find more details and examples below.

Visit the api-docs for the complete schema.

Defining inputs: spec definition

Inside the spec_definition, each key of the properties object describes one expected input key of the chart.

An input is either a custom property or uses one of the available features such as labels.

Custom properties

E.g. for a spec_definition like:

{
  "spec_definition": {
      "properties": {
          "custom": {
              "type": "schema",
              "schema": {
                  "type": "string"
              }
          }
      }
  }
}

The chart would accept the following input:

custom: some-string

Using Placeholders in custom properties is not supported.

Properties using features

In addition to plain properties of type: schema, a Workload Profile can also reference Humanitec features. They are a building block of predefined properties and specific UI / API behavior.

An example spec_definition that consists only of annotations and labels, using the Humanitec features could look like this:

{
    "spec_definition": {
        "properties": {
            "annotations": {
                "feature_name": "humanitec/annotations",
                "type": "feature",
                "version": "0.1"
            },
            "labels": {
                "feature_name": "humanitec/labels",
                "type": "feature",
                "version": "0.1"
            }
        }
    }
}

In addition to top-level features, features can also be listed inside the containers’ collection. This will tell the system that this feature should be shown for every container of the Workload.

A Workload with labels and multiple containers that each support a custom image could look like:

{
    "spec_definition": {
        "properties": {
            "labels": {
                "feature_name": "humanitec/labels",
                "type": "feature",
                "version": "0.1"
            },
            "containers": {
                "feature_name": "humanitec/containers",
                "properties": {
                    "image": {
                        "feature_name": "humanitec/image",
                        "type": "feature",
                        "version": "0.1"
                    }
                },
                "title": "Containers",
                "type": "collection",
                "version": "0.1"
            },
        }
    }
}

In addition to choosing between feature and schema, the UI behavior of properties can be customized:

  • title the title of the input group.
  • ui_hints: {} provide the following capabilities.
    • order allows to change the rendering of inputs in the UI.
    • hidden allows to hide an input in the UI.

You can find a full list of features here. Refer to the examples for each feature on how to apply these UI customizations to them.

Workload Profile Chart reference

The workload_profile_chart element references the Helm chart that should be used by this Workload Profile. The Helm chart must be registered as a “Workload Profile Chart” in the Platform Orchestrator. It is either one of the built-in charts like humanitec/default-module, or a custom chart registered as a Custom Workload Profile Chart.

The workload_profile_chart reference needs to include the chart version, which can be latest.

Valid values could be:

  • Reference a specific version

    { "workload_profile_chart": { "id": "my-chart", "version": "1.2.3" }}

  • Reference the latest chart version

    { "workload_profile_chart": { "id": "my-chart", "version": "latest" }}

  • Reference a chart version from the humanitec org

    { "workload_profile_chart": { "id": "humanitec/default-module", "version": "latest" }}

As managing your spec_definition on the command line can be tedious, we recommend using a file instead.

Assuming a profile.json file in the current directory, which contains an object with a spec_definition property, you can create a Custom Workload Profile like this.

Set the following environment variables:

Variable Example Description
HUMANITEC_TOKEN lsakdjhcals A Humanitec token of a user with the Administrator role on the Organization. Go here to see how to create one.
HUMANITEC_ORG my-org The Humanitec organization the Application is in.
WORKLOAD_PROFILE example-profile The id of the Workload Profile

Prepare the payload:

payload=$(cat profile.json | \
  jq -rM '. + {"id": "'${WORKLOAD_PROFILE}'", "version": "1.0.0", "workload_profile_chart": { "id": "humanitec/default-module", "version": "latest" } }')

Submit the Workload Profile:

humctl api post /orgs/${HUMANITEC_ORG}/workload-profiles \
  -d "$payload"


curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/workload-profiles" \
  -X POST \
  -H "Authorization: Bearer $HUMANITEC_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$payload"

Inspect built-in Workload Profiles

You can look at the spec_definition of the built-in Workload Profiles for usage examples:

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


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

Usage

Custom Workload Profiles can be referenced by {orgId}/{profileId} or {profileId}. Visit Workload Profiles for a more detailed example.

Built-in Workload Profiles

Custom Workload Profile Charts