Features

Overview

Features are building blocks for constructing Workload Profiles . They bundle predefined properties and specific UI / API behavior.

The Platform Orchestrator’s built-in Workload Profiles are composed out of features. You can also use these features to help build Custom Workload Profiles quickly.

The following features are available. Keep in mind that some features have dependencies on others to work, as stated in the Requires column.

Runtime only features don’t influence the editing interface of a Workload, but are used to enable specific capabilities when viewing a running Workload.

Top-level features

Feature Description Requires
humanitec/annotations [DEPRECATED - use the humanitec/deployment , humanitec/pod , humanitec/cronjob and humanitec/job features instead to define annotations on your Workload
humanitec/containers Contains a list of containers. The available container sub-features are described below.
humanitec/cronjob Define properties for the Kubernetes CronJob. humanitec/job
humanitec/deployment Define properties for the Kubernetes Deployment. humanitec/pod
humanitec/ingress [DEPRECATED - use a route instead] Configure an ingress resource humanitec/service to add the necessary ports
humanitec/image-pull-secrets [DEPRECATED - see Container Registries for guidance] Define image pull secrets. (Required if you Humanitec manages your registry credentials or use the built in registry)
humanitec/job Define properties for the Kubernetes Job. humanitec/pod
humanitec/labels [DEPRECATED - use the humanitec/deployment , humanitec/pod , humanitec/cronjob and humanitec/job features instead] Define labels on your Workload
humanitec/pod Define properties for the Kubernetes Pod.
humanitec/replicas [DEPRECATED - use the humanitec/deployment feature instead] (Runtime only) Enable the modification of the replica count in the UI.
humanitec/schedules Define schedules e.g. in a cronjob Workload
humanitec/service-account [DEPRECATED - use the humanitec/pod feature instead] Specify a service account
humanitec/service Define service ports and container ports
humanitec/volumes Define additional volumes. (Usually hidden)
humanitec/extra-containers Additional containers that might be injected by the Platform Orchestrator. (Usually hidden)
humanitec/extra-variables Additional variables that might be injected by the Platform Orchestrator. (Usually hidden)
humanitec/extra-volumes Additional volumes that might be injected by the Platform Orchestrator. (Usually hidden)

Sub-features

Sub-features are usually used inside a humanitec/container collection.

Feature Description Requires
humanitec/image Select a container image.
humanitec/variables Provides variables that can be used in a container, with support for resolving Humanitec placeholders to resources and values. humanitec/env (inside humanitec/container) to mount the resulting environment variables. humanitec/annotations to re-deploy your Workload in case of changes.
humanitec/files Mount files as volumes humanitec/volume-mounts (inside humanitec/container) to mount the resulting volumes.humanitec/extra-variables to hold the file content.
humanitec/volume-mounts Define volume mount inside the container
humanitec/probe Configure a probe (can be used inside liveness or readiness probes)
humanitec/resources Defined container resources
humanitec/overrides Use for CMD or ARG overrides
humanitec/envs Define environment variables. (Usually hidden)
humanitec/logs (Runtime only) Surface container logs inside the UI.

JSON schema

The complete JSON input schema for each feature can be fetched from the Humanitec API.

Set the following environment variables:

Variable Example Description
HUMANITEC_TOKEN lsakdjhcals A Humanitec token of a user with the Member or above role on the Organization.
HUMANITEC_ORG my-org The Humanitec organization the Application is in. 

humctl api get /orgs/${HUMANITEC_ORG}/workload-profile-features \
  | jq .


curl -H "Authorization: Bearer $HUMANITEC_TOKEN" \
  https://api.humanitec.io/orgs/${HUMANITEC_ORG}/workload-profile-features \
  | jq .

humanitec/annotations

The annotations feature defines Annotations that are added to Pods generated for the Workload. Depending on how this feature is implemented by the Workload Profile itself, this may only make up a subset of annotations on the Pod.

Annotations are defined as a map with keys and values.

Keys are made up of an optional prefix followed by a name, separated by a slash (/).

  • The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between.
  • The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/).

Values do not have any validation requirements.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "annotations": {
        "feature_name": "humanitec/annotations",
        "type": "feature",
        "version": "0.1"
      }
    }
  }
}
Score file:

score.yaml:

apiVersion: score.dev/v1b1
metadata:
  name: my-workload
  annotations:
    podscoreannotationkey: podscoreannotationvalue

containers:
  demo:
    image: registry/my-image:1.0.0
service:
  ports:
    http:
      port: 80
      targetPort: 8080

Score extension file:

humanitec.score.yaml:

apiVersion: humanitec.org/v1b1

spec:
  # Set annotations on the Kubernetes Deployment
  deployment:
    annotations:
      deploymentannotationkey: deploymentannotationvalue
  # Set annotations on the Kubernetes Pod
  pod:
    annotations:
      podannotationkey: podannotationvalue
  # Set annotations on the Kubernetes Service
  service:
    annotations:
      serviceannotationkey: serviceannotationvalue

Resulting Deployment Set snippet:


{
  "annotations": {
    "annotationkey": "annotationvalue",
    "humanitec.io/managed-by": "Score"
  },
  "service": {
    "annotations": {
      "serviceannotationkey": "serviceannotationvalue"
    }
  }
}

humanitec/containers

The containers feature allows containers to be added to a Workload. The structure is a map with user-provided IDs as keys and container objects as values. Containers can have various sub-features.

humanitec/containers - envs

Define environment variables. Environment variables defined via the Score extension file don’t support placeholders . They aren’t exposed by default in the UI.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "containers": {
        "feature_name": "humanitec/containers",
        "title": "Containers",
        "type": "collection",
        "version": "0.1",
        "properties": {
          "env": {
            "feature_name": "humanitec/envs",
            "type": "feature",
            "ui_hints": {
              "hidden": true
            },
            "version": "0.1"
          },
        }
      }
    }
  }
}
Score file: 
apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    image: "registry/my-image:1.0.0"

Score extension file:

humanitec.score.yaml:

apiVersion: humanitec.org/v1b1

spec:
  containers:
    demo:
      variables:
        SOME: VARIABLE
        SHARED_VALUE: $${values.SOMETHING}

Resulting Deployment Set snippet:

{
  "containers": {
    "demo": {
      "env": [
        {
          "name": "SOME",
          "value": "VARIABLE"
        }
      ],
      "id": "demo",
      "image": "registry/my-image:1.0.0"
    }
  }
}

humanitec/containers - files

The top level of the files object is a map with file paths as keys and file objects as values. The file paths must be rooted and include at least one directory. They cannot be nested inside any mount points defined in volume_mounts .

Note that in the Workload Profile Definition, the features volume_mounts and extra-variables must also be configured as they are a required dependency.

Property Type Description
mode String A Unix style permission bitmask in Octal format.
value String The content of the file.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "containers": {
        "feature_name": "humanitec/containers",
        "title": "Containers",
        "type": "collection",
        "version": "0.1",
        "properties": {
          "files": {
            "feature_name": "humanitec/files",
            "type": "feature",
            "version": "0.1"
          },
          "volume_mounts": {
            "feature_name": "humanitec/volume-mounts",
            "title": "Volume mounts",
            "type": "feature",
            "version": "0.1"
          }
        }
      },
      "variables": {
        "feature_name": "humanitec/extra-variables",
        "type": "feature",
        "ui_hints": {
            "hidden": true
        },
        "version": "0.1"
      }
    }
  }
}
Score file:

score.yaml:

apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    image: registry/my-image:1.0.0
    files:
      - target: /app/default.config
        mode: "0644"
        content: |
          [config]
          key=value

Score extension file:

# Not required for this feature

Resulting Deployment Set snippet:

{
  "containers": {
    "demo": {
      "files": {
        "/app/default.config": {
          "mode": "0644",
          "value": "[config]\nkey=value\n"
        }
      }
    }
  }
}

humanitec/containers - image

Define the image of a container.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "containers": {
        "feature_name": "humanitec/containers",
        "title": "Containers",
        "type": "collection",
        "version": "0.1",
        "properties": {
          "image": {
            "feature_name": "humanitec/image",
            "type": "feature",
            "version": "0.1"
          }
        }
      }
    }
  }
}
Score file: 
apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    image: "registry/my-image:1.0.0"

Score extension file:

# Not required for this feature

Resulting Deployment Set snippet:

{
  "containers": {
    "demo": {
      "id": "demo",
      "image": "registry/my-image:1.0.0"
    }
  }
}

humanitec/containers - logs (runtime only)

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "containers": {
        "feature_name": "humanitec/containers",
        "title": "Containers",
        "type": "collection",
        "version": "0.1",
        "properties": {},
        "runtime_properties": [{
          "feature_name": "humanitec/logs",
          "title": "Container logs",
          "type": "feature",
          "ui_hints": {
              "order": 0
          },
          "version": "0.1"
        }]
      }
    }
  }
}
Score file: 
# Not required for this feature

Score extension file:

# Not required for this feature

Resulting Deployment Set snippet:

(No change to the Deployment Set)

humanitec/containers - overrides

Provide overrides for container commands or arguments.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "containers": {
        "feature_name": "humanitec/containers",
        "title": "Containers",
        "type": "collection",
        "version": "0.1",
        "properties": {
          "args": {
            "feature_name": "humanitec/overrides",
            "title": "Argument overrides",
            "type": "feature",
            "ui_hints": {
                "order": 9
            },
            "version": "0.1"
          },
          "command": {
            "feature_name": "humanitec/overrides",
            "title": "Command overrides",
            "type": "feature",
            "ui_hints": {
                "order": 8
            },
            "version": "0.1"
          }
        }
      }
    }
  }
}
Score file:

score.yaml:

apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    image: registry/my-image:1.0.0
    command: ["/bin/sh"]
    args: ["-c", "while true; do printenv && sleep 60; done"]

Score extension file:

# Not required for this feature

Resulting Deployment Set snippet:

{
  "containers": {
    "demo": {
      "args": [
        "-c",
        "while true; do printenv \u0026\u0026 sleep 60; done"
      ],
      "command": [
        "/bin/sh"
      ],
      "id": "demo",
      "image": "busybox"
    }
  }
}

humanitec/containers - probe

A probe can be of four types: command, http, grpc or tcp. The supported properties depend on the value of the type property.

The following properties are available in all probes:

Property Type Description
initialDelaySeconds Integer Number of seconds after the container has started before probes are initiated.
periodSeconds Integer The number of seconds between probes.
timeoutSeconds Integer Number of seconds after which the probe times out. Defaults to 1 second.
successThreshold Integer Minimum consecutive successes for the probe to be considered successful after having failed.
failureThreshold Integer Minimum consecutive failures for the probe to be considered failed after having succeeded.

Properties for type “http”

Property Type Description
headers Map of strings A key value map of HTTP headers and their values.
path String The HTTP path for the request. Must start with /.
port Integer The port to connect to. Must be in range 1 - 65535.

Usage in Score: see the complete example below .

Properties for type “command”

Property Type Description
command Array of strings The command to run.

Usage in Score:

Score file: 
apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    image: "registry/my-image:1.0.0"
Score extension file: 
apiVersion: humanitec.org/v1b1

spec:
  containers: 
    demo:
      liveness_probe:
        type: command
        command:
          - "bash"
          - "-c"
          - "/app/is_alive.sh"

Properties for type “grpc”

Property Type Description
port Integer The port to connect to. Must be in range 1 - 65535.

Usage in Score:

Score file: 
apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    image: "registry/my-image:1.0.0"
Score extension file: 
apiVersion: humanitec.org/v1b1

spec:
  containers: 
    demo:
      liveness_probe:
        type: grpc
        port: 7001

Properties for type “tcp”

Property Type Description
port Integer The port to connect to. Must be in range 1 - 65535.

Usage in Score

Score file: 
apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    image: "registry/my-image:1.0.0"
Score extension file: 
apiVersion: humanitec.org/v1b1

spec:
  containers: 
    demo:
      liveness_probe:
        type: tcp
        port: 7001

humanitec/containers - probe: Complete example

The Score examples below show the most commonly used http type probes. See the examples above for the other types.

The Workload Profile definition is identical regardless of the types of probes being used.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "containers": {
        "feature_name": "humanitec/containers",
        "title": "Containers",
        "type": "collection",
        "version": "0.1",
        "properties": {
          "liveness_probe": {
            "feature_name": "humanitec/probe",
            "title": "Liveness Probe",
            "type": "feature",
            "ui_hints": {
                "order": 5
            },
            "version": "0.1"
          },
          "readiness_probe": {
            "feature_name": "humanitec/probe",
            "title": "Readiness Probe",
            "type": "feature",
            "ui_hints": {
                "order": 6
            },
            "version": "0.1"
          }
        }
      }
    }
  }
}
Score file:

score.http.yaml:

apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    image: registry/my-image:1.0.0
    livenessProbe:
      httpGet:
        path: "/alive"
        port: 8080
    readinessProbe:
      httpGet:
        path: "/ready"
        port: 8080

Score extension file:

# Required for types other than http only.

# See the examples above.

Resulting Deployment Set snippet:

"containers": {
  "demo": {
    "id": "demo",
    "image": "registry/my-image:1.0.0",
    "liveness_probe": {
      "path": "/alive",
      "port": 8080,
      "type": "http"
    },
    "readiness_probe": {
      "path": "/ready",
      "port": 8080,
      "type": "http"
    }
  }
}

humanitec/containers - resources

Specify the minimum and maximum resources required for this container. Pods will not be scheduled unless the minimum requested resources are available for all containers in a Pod on a node. The Pod will either be throttled or terminated if the maximum resource limit is reached.

The minimum resource is specified by the requests property. The maximum resource is specified by the limits property.

Each of these properties supports the following:

Property Type Description
cpu String A decimal number representing the fractional number of CPUs. e.g. 0.25.
memory String The amount of memory as an integer number of bytes. The numbers can be scaled by appending E, P, T, G, M, k or their power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki to the end of the number.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "containers": {
        "feature_name": "humanitec/containers",
        "title": "Containers",
        "type": "collection",
        "version": "0.1",
        "properties": {
          "resources": {
            "feature_name": "humanitec/resources",
            "title": "Assign Resources",
            "type": "feature",
            "version": "0.1"
          },
        }
      }
    }
  }
}
Score file:

score.yaml:

apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    image: registry/my-image:1.0.0
    resources:
      limits:
        cpu: "0.250"
        memory: "256Mi"
      requests:
        cpu: "0.025"
        memory: "64Mi"

Score extension file:

# Not required for this feature

Resulting Deployment Set snippet:

{
  "containers": {
    "demo": {
      "id": "demo",
      "image": "registry/my-image:1.0.0",
      "resources": {
        "limits": {
          "cpu": "0.250",
          "memory": "256Mi"
        },
        "requests": {
          "cpu": "0.025",
          "memory": "64Mi"
        }
      }
    }
  }
}

humanitec/containers - variables

Environment variables are specified as a map of keys and values where both keys and values are strings. Keys must only contain alphanumeric characters, -, _ or .. There is no restriction on the values.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "containers": {
        "feature_name": "humanitec/containers",
        "title": "Containers",
        "type": "collection",
        "version": "0.1",
        "properties": {
          "env": {
            "feature_name": "humanitec/envs",
            "type": "feature",
            "ui_hints": {
              "hidden": true
            },
            "version": "0.1"
          },
          "variables": {
            "feature_name": "humanitec/variables",
            "type": "feature",
            "version": "0.1"
          }
        }
      }
    }
  }
}
Score file:

score.yaml:

apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    image: registry/my-image:1.0.0
    variables:
      API_KEY: "${resources.env.API_KEY}"
resources:
  env:
    # The type "environment" is available per the Score specification.
    type: environment

Score extension file:

# Not required for this feature

Resulting Deployment Set snippet:

{
  "containers": {
    "demo": {
      "id": "demo",
      "image": "registry/my-image:1.0.0",
      "variables": {
        "API_KEY": "${values.API_KEY}"
      }
    }
  }
}

humanitec/containers - volume-mounts

The top level of the volume_mounts object is a map with mount points paths as keys and volume mount objects as values. The mount points must be rooted paths and include at least one directory. They cannot be nested inside any other defined mount points or be a parent of any file specified in the Files section.

Both volumes provisioned via Humanitec Resources or as built-in types are supported.

Persistent Volumes are managed through the Resources system and must be referenced via their Resource ID, e.g. shared.nfs-share. Other volume types must be referenced via the definition in the volumes section, e.g. volumes.common-dir.

Property Type Description
id String The resource ID or volume ID to mount.
read_only Boolean Defines whether the volume should be mounted as read-only.
sub_path String Specifies a sub-directory in the volume to mount. Must be a relative path .

Note that in the Workload Profile Definition, the feature extra-variables must also be configured as it is a required dependency.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "containers": {
        "feature_name": "humanitec/containers",
        "title": "Containers",
        "type": "collection",
        "version": "0.1",
        "properties": {
          "volume_mounts": {
            "feature_name": "humanitec/volume-mounts",
            "title": "Volume mounts",
            "type": "feature",
            "version": "0.1"
          }
        }
      },
      "variables": {
        "feature_name": "humanitec/extra-variables",
        "type": "feature",
        "ui_hints": {
            "hidden": true
        },
        "version": "0.1"
      }
    }
  }
}
Score file:

score.yaml:

apiVersion: score.dev/v1b1
metadata:
  name: my-workload
containers:
  my-container:
    image: .
    volumes:
    - source: ${resources.my-pvc}
      target: /target/dir
    - source: ${resources.my-ebs}
      target: /ebs-target/dir
    - source: ${resources.my-ephemeral-volume}
      target: /tmp/dir
    - source: ${resources.my-nfs}
      target: /nfs-target/dir
resources:
  my-pvc:
    type: volume
  my-ebs:
    type: volume
    class: ebs
  my-ephemeral-volume:
    type: volume
    class: ephemeral
  my-nfs:
    type: volume
    class: nfs

Score extension file:

# Not required for this feature

Resulting Deployment Set snippet:

{
  "containers": {
    "demo": {
      "id": "demo",
      "image": "registry/my-image:1.0.0",
      "volume_mounts": {
        "/mnt/data": {
          "id": "volumes.tmp-pod",
          "read_only": false,
          "sub_path": ""
        }
      }
    }
  },
  "volumes": {
    "tmp-pod": {
      "source": {
        "sizeLimit": "1024Mi"
      },
      "type": "emptyDir"
    }
  }
}

humanitec/cronjob

The cronjob feature lets you specify properties as defined by the Kubernetes CronJob specification.

Description

You can define these properties of the CronJob object:

  • annotations and labels which will be placed in the CronJob’s metadata
  • Any properties of the CronJobSpec except jobTemplate and schedule

The schedule itself is configured through the humanitec/schedules feature.

The cronjob feature uses the humanitec/job feature to define the Job objects created out of the CronJob.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "cronjob": {
        "feature_name": "humanitec/cronjob",
        "type": "feature",
        "ui_hints": {
            "hidden": true
        },
        "version": "0.1"
      }
    }
  }
}
Score file:

score.yaml:

apiVersion: score.dev/v1b1

metadata:
  name: my-cronjob

containers:
  main-container:
    image: registry/my-image:1.0.0

Score extension file:

humanitec.score.yaml:

apiVersion: humanitec.org/v1b1
# Select the "default-cronjob" built-in Workload Profile
profile: humanitec/default-cronjob

spec:
  # Define the CronJob schedules
  schedules:
    6-hour-run:
      containers:
        main-container:
          args:
            - "--hours"
            - "6"
      schedule: "15 1,7,13,19 * * *"
  cronjob:
    # Set annotations and labels in the CronJob object metadata
    annotations:
      cronjobannotationkey: cronjobannotationvalue
    labels:
      cronjoblabelkey: cronjoblabelvalue
    # Set properties of the CronJobSpec, e.g.:
    timeZone: Africa/Lagos
    concurrencyPolicy: Forbid
  job:
    # Set annotations and labels in the Job object metadata for the Jobs created out of the CronJob
    annotations:
      jobannotationkey: jobannotationvalue
    labels:
      joblabelkey: joblabelvalue
    # Set properties of the JobSpec, e.g.:
    activeDeadlineSeconds: 30
    ttlSecondsAfterFinished: 3600
  pod:
    # Set Pod annotations and labels in Pod metadata
    annotations:
      podannotationkey: podannotationvalue
    labels:
      podlabelkey: podlabelvalue
    # Set properties of the PodSpec, e.g.:
    nodeSelector:
      topology.kubernetes.io/region: europe-west3
    os:
      name: linux

Resulting Deployment Set snippet:


{
  "containers": {
    "main-container": {
      "id": "main-container",
      "image": "registry/my-image:1.0.0"
    }
  },
  "cronjob": {
    "annotations": {
      "cronjobannotationkey": "cronjobannotationvalue"
    },
    "concurrencyPolicy": "Forbid",
    "labels": {
      "cronjoblabelkey": "cronjoblabelvalue"
    },
    "timeZone": "Africa/Lagos"
  },
  "job": {
    "activeDeadlineSeconds": 30,
    "annotations": {
      "jobannotationkey": "jobannotationvalue"
    },
    "labels": {
      "joblabelkey": "joblabelvalue"
    },
    "ttlSecondsAfterFinished": 3600
  },
  "pod": {
    "annotations": {
      "podannotationkey": "podannotationvalue"
    },
    "labels": {
      "podlabelkey": "podlabelvalue"
    },
    "nodeSelector": {
      "topology.kubernetes.io/region": "europe-west3"
    },
    "os": {
      "name": "linux"
    }
  },
  "schedules": {
    "6-hour-run": {
      "containers": {
        "main-container": {
          "args": [
            "--hours",
            "6"
          ]
        }
      },
      "schedule": "15 1,7,13,19 * * *"
    }
  }
}

humanitec/deployment

The deployment feature lets you specify properties as defined by the Kubernetes Deployment specification.

Description

You can define these properties of the Deployment object:

  • annotations and labels which will be placed in the Deployment’s metadata
  • Any properties of the DeploymentSpec except selector and template

The deployment feature uses the humanitec/pod feature to define the Pod objects created out of the Job.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "deployment": {
        "feature_name": "humanitec/deployment",
        "type": "feature",
        "ui_hints": {
            "hidden": true
        },
        "version": "0.1"
      }
    }
  }
}
Score file: 
apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    image: registry/my-image:1.0.0

Score extension file:

humanitec.score.yaml:

apiVersion: humanitec.org/v1b1

spec:
  deployment:
    # Set annotations and labels in the Deployment object metadata
    annotations:
      deploymentannotationkey: deploymentannotationvalue
    labels:
      deploymentlabelkey: deploymentlabelvalue
    # Set properties of the DeploymentSpec, e.g.:
    minReadySeconds: 10
    replicas: 2
    strategy:
      rollingUpdate:
        maxSurge: 30%
  # Set properties of the PodSpec, e.g.:
  pod:
    nodeSelector:
      topology.kubernetes.io/region: europe-west3
    os:
      name: linux

Resulting Deployment Set snippet:


{
  "deployment": {
    "annotations": {
      "deploymentannotationkey": "deploymentannotationvalue"
    },
    "labels": {
      "deploymentlabelkey": "deploymentlabelvalue"
    },
    "minReadySeconds": 10,
    "replicas": 2,
    "strategy": {
      "rollingUpdate": {
        "maxSurge": "30%"
      }
    }
  },
  "pod": {
    "nodeSelector": {
      "topology.kubernetes.io/region": "europe-west3"
    },
    "os": {
      "name": "linux"
    }
  }
}

humanitec/job

The job feature lets you specify properties as defined by the Kubernetes Job specification.

Description

You can define these properties of the Job object:

  • annotations and labels which will be placed in the Job’s `metadata
  • Any properties of the JobSpec except selector and template

The job feature uses the humanitec/pod feature to define the Pod objects created out of the Job.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "job": {
        "feature_name": "humanitec/job",
        "type": "feature",
        "ui_hints": {
            "hidden": true
        },
        "version": "0.1"
      }
    }
  }
}
Score file: 
apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    image: registry/my-image:1.0.0

Score extension file:

humanitec.score.yaml:

apiVersion: humanitec.org/v1b1
# Select the "default-job" bulit-in Workload Profile
profile: humanitec/default-job

spec:
  job:
    # Set annotations and labels in the Job object metadata
    annotations:
      jobannotationkey: jobannotationvalue
    labels:
      joblabelkey: joblabelvalue
    # Set properties of the JobSpec, e.g.:
    activeDeadlineSeconds: 30
    ttlSecondsAfterFinished: 3600
  pod:
    # Set Pod annotations and labels in Pod metadata
    annotations:
      podannotationkey: podannotationvalue
    labels:
      podlabelkey: podlabelvalue
    # Set properties of the PodSpec, e.g.:
    nodeSelector:
      topology.kubernetes.io/region: europe-west3
    os:
      name: linux

Resulting Deployment Set snippet:


{
  "job": {
    "activeDeadlineSeconds": 30,
    "annotations": {
      "jobannotationkey": "jobannotationvalue"
    },
    "labels": {
      "joblabelkey": "joblabelvalue"
    },
    "ttlSecondsAfterFinished": 3600
  },
  "pod": {
    "annotations": {
      "podannotationkey": "podannotationvalue"
    },
    "labels": {
      "podlabelkey": "podlabelvalue"
    },
    "nodeSelector": {
      "topology.kubernetes.io/region": "europe-west3"
    },
    "os": {
      "name": "linux"
    }
  }
}

humanitec/labels

The labels feature defines Labels that will be added to Pods generated for the Workload. Depending on how this feature is implemented by the Workload Profile itself, this may only make up a subset of labels on the Pod.

Description

Labels are defined as a map with keys and values.

Keys are made up of an optional prefix followed by a name, separated by a slash (/).

  • The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between.
  • The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/).

Valid label value:

  • Must be 63 characters or less (can be empty).
  • Unless empty, must begin and end with an alphanumeric character ([a-z0-9A-Z]).
  • May contain dashes (-), underscores (_), dots (.), and alphanumerics in between.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "labels": {
        "feature_name": "humanitec/labels",
        "type": "feature",
        "version": "0.1"
      }
    }
  }
}
Score file:

score.yaml:

apiVersion: score.dev/v1b1
metadata:
  name: my-workload

service:
  ports:
    http:
      port: 80
      targetPort: 8080

containers:
  demo:
    image: registry/my-image:1.0.0

Score extension file:

humanitec.score.yaml:

apiVersion: humanitec.org/v1b1

spec:
  # Set labels on the Kubernetes Deployment
  deployment:
    labels:
      deploymentlabelkey: deploymentlabelvalue
  # Set labels on the Kubernetes Pod
  pod:
    labels:
      podlabelkey: podlabelvalue
  # Set labels on the Kubernetes Service
  service:
    labels:
      servicelabelkey: servicelabelvalue

Resulting Deployment Set snippet:


{
  "containers": {
    "demo": {
      "id": "demo",
      "image": "registry/my-image:1.0.0"
    },
    "labels": {
      "labelkey": "labelvalue"
    },
    "service": {
      "labels": {
        "servicelabelkey": "servicelabelvalue"
      }
    }
  }
}

humanitec/pod

The pod feature lets you specify properties as defined by the Kubernetes Pod specification.

Description

You can define these properties of the Job object:

  • annotations and labels which will be placed in the Pod’s `metadata
  • Any properties of the PodSpec except containers. Use the humanitec/containers feature to set properties of the container

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "pod": {
        "feature_name": "humanitec/pod",
        "type": "feature",
        "ui_hints": {
            "hidden": true
        },
        "version": "0.1"
      }
    }
  }
}
Score file: 
apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    image: registry/my-image:1.0.0

Score extension file:

humanitec.score.yaml:

apiVersion: humanitec.org/v1b1

spec:
  pod:
    # Set Pod annotations and labels in the Pod metadata
    annotations:
      podannotationkey: podannotationvalue
    labels:
      podlabelkey: podlabelvalue
    # Set properties of the PodSpec, e.g.:
    nodeSelector:
      topology.kubernetes.io/region: europe-west3
    os:
      name: linux

Resulting Deployment Set snippet:


{
  "pod": {
    "annotations": {
      "podannotationkey": "podannotationvalue"
    },
    "labels": {
      "podlabelkey": "podlabelvalue"
    },
    "nodeSelector": {
      "topology.kubernetes.io/region": "europe-west3"
    },
    "os": {
      "name": "linux"
    }
  }
}

humanitec/replicas (runtime only)

The replicas feature is a runtime only feature. It can be used to adjust the number of replicas on Workload Profiles that are implemented using Deployments or ReplicaSets.

To restart all Deployments in an Application Environment, see pause Environments .

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {},
    "runtime_properties": [{
      "feature_name": "humanitec/replicas",
      "type": "feature",
      "ui_hints": {
          "order": -2
      },
      "version": "0.1"
    }]
  }
}
Score file: 
# Not required for this feature

Score extension file:

# Not required for this feature

Resulting Deployment Set snippet:

(No change to the Deployment Set)

humanitec/schedules

The schedules feature defines one or more schedules under which the Workload should run as a Kubernetes CronJob .

For detailed configuration of the CronJob itself, use the humanitec/cronjob feature in conjunction with schedules.

Description

Kubernetes CronJobs must have exactly one cron expression defined for them. This feature provides the convenience of creating sets of CronJobs with the same basic configuration, but running on different schedules. As an extra level of flexibility, the command and arguments for the container can optionally be overridden.

The top level is a Map of schedule objects. The key must be a valid Humanitec ID. If empty, it will produce an error.

The schedule object has the following properties:

Property Type Description
schedule String A valid cron expression .
containers Object A Map with keys of container IDs in the Workload. The values are objects containing command and arg overrides.

This example shows schedules for a CronJob with one container with the id main-container. The schedule is every six hours.

The Score extension file specifies the humanitec/default-cronjob Workload Profile to use which includes the feature.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "schedules": {
        "feature_name": "humanitec/schedules",
        "type": "feature",
        "version": "0.1"
      }
    }
  }
}
Score file:

score.yaml:

apiVersion: score.dev/v1b1

metadata:
  name: my-cronjob

containers:
  main-container:
    image: registry/my-image:1.0.0

Score extension file:

humanitec.score.yaml:

apiVersion: humanitec.org/v1b1
# Select the "default-cronjob" built-in Workload Profile
profile: humanitec/default-cronjob

spec:
  # Define the CronJob schedules
  schedules:
    6-hour-run:
      containers:
        main-container:
          args:
            - "--hours"
            - "6"
      schedule: "15 1,7,13,19 * * *"
  cronjob:
    # Set annotations and labels in the CronJob object metadata
    annotations:
      cronjobannotationkey: cronjobannotationvalue
    labels:
      cronjoblabelkey: cronjoblabelvalue
    # Set properties of the CronJobSpec, e.g.:
    timeZone: Africa/Lagos
    concurrencyPolicy: Forbid
  job:
    # Set annotations and labels in the Job object metadata for the Jobs created out of the CronJob
    annotations:
      jobannotationkey: jobannotationvalue
    labels:
      joblabelkey: joblabelvalue
    # Set properties of the JobSpec, e.g.:
    activeDeadlineSeconds: 30
    ttlSecondsAfterFinished: 3600
  pod:
    # Set Pod annotations and labels in Pod metadata
    annotations:
      podannotationkey: podannotationvalue
    labels:
      podlabelkey: podlabelvalue
    # Set properties of the PodSpec, e.g.:
    nodeSelector:
      topology.kubernetes.io/region: europe-west3
    os:
      name: linux

Resulting Deployment Set snippet:

{
  "schedules": {
    "6-hour-run": {
      "containers": {
        "main-container": {
          "args": [
            "--hours",
            "6"
          ]
        }
      },
      "schedule": "15 1,7,13,19 * * *"
    }
  }
}

humanitec/service

The service feature defines how a service for the Workload is configured.

Description

The top level of the service feature only contains the property ports.

The ports property is a Map or port objects. The Key must be a valid Humanitec ID.

The port object has the following properties:

Property Type Description
service_port Integer The port exposed by the service. Must be in range 1 - 65535
container_port Integer The port a container in the Pod is listening on. Traffic will be mapped from service_port to container_port. If not specified, no mapping will occur. Must be in range 1 - 65535.
protocol String Must be one of TCP, UDP or SCTP.

This example shows a service configured with two ports. One exposes port 8080 and maps to port 3001 on the container. The other listens on 90245 expecting a UDP connection.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "service": {
        "feature_name": "humanitec/service",
        "type": "feature",
        "version": "0.1"
      }
    }
  }
}
Score file:

score.yaml:

apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    image: registry/my-image:1.0.0
service:
  ports:
    www:
      port: 8080
      targetPort: 3001
    stream:
      port: 19245
      targetPort: 19245
      protocol: UDP

Score extension file:

# Not required for this feature

Resulting Deployment Set snippet:

{
  "service": {
    "ports": {
      "www": {
        "container_port": 3001,
        "protocol": "TCP",
        "service_port": 8080
      },
      "stream": {
        "container_port": 19245,
        "protocol": "UDP",
        "service_port": 19245
      }
    }
  }
}

humanitec/service-account

The service-account feature defines the Kubernetes Service Account that Pods in the Workload should run as. It does not manage the creation of that Service Account.

Description

The property is just a string which must be a service account that exists in the cluster.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "serviceAccountName": {
        "feature_name": "humanitec/service-account",
        "type": "feature",
        "version": "0.1"
      }
    }
  }
}
Score file: 
apiVersion: score.dev/v1b1
metadata:
  name: my-workload

containers:
  demo:
    image: registry/my-image:1.0.0

Score extension file:

humanitec.score.yaml:

apiVersion: humanitec.org/v1b1

spec:
  pod:
    serviceAccountName: data-access-service-account

Resulting Deployment Set snippet:

{
  "serviceAccountName": "data-access-service-account"
}

humanitec/volumes

The volumes feature defines volumes that are not provisioned via the Humanitec resources system for example emptyDir.

Description

The top level of the volumes feature is a map of volumes. The Keys must be valid Humanitec IDs.

The volume object has the following properties:

Property Type Description
source Object This must follow the Kubernetes Volume Type source schema depending on the type specified in type.
type String A valid Kubernetes Volume Type .

The example below shows an emptyDir with a 1 GB size limit. Note that it covers the volume declaration only, not the volume mount. See the humanitec/containers - volume-mounts feature for an example on mounting the volume.

Configuration and examples

DefinitionUsage in Score
Workload Profile definition: 
{
  "spec_definition": {
    "properties": {
      "volumes": {
        "feature_name": "humanitec/volumes",
        "type": "feature",
        "version": "0.1"
      }
    }
  }
}
Score file:

score.yaml:

apiVersion: score.dev/v1b1
metadata:
  name: my-workload
containers:
  my-container:
    image: .
    volumes:
    - source: ${resources.my-pvc}
      target: /target/dir
    - source: ${resources.my-ebs}
      target: /ebs-target/dir
    - source: ${resources.my-ephemeral-volume}
      target: /tmp/dir
    - source: ${resources.my-nfs}
      target: /nfs-target/dir
resources:
  my-pvc:
    type: volume
  my-ebs:
    type: volume
    class: ebs
  my-ephemeral-volume:
    type: volume
    class: ephemeral
  my-nfs:
    type: volume
    class: nfs

Score extension file:

# Not required for this feature

Resulting Deployment Set snippet:

{
  "volumes": {
    "common-dir": {
      "source": {
        "sizeLimit": "1024Mi"
      },
      "type": "emptyDir"
    }
  }
}

Custom Workload Profile Charts