Workloads

A Workload in Humanitec is a representation of the code that runs in a Kubernetes cluster, typically as a pod. A Workload is made up of one or more Containers, along with their configuration, such as the container image, Environment variables, and resource requirements.

In most cases, a Workload is a back-end service or a front-end of an Application. For example, in a microservice architecture, each service would be represented by a Workload in Humanitec. This allows developers to manage and deploy their code in a more organized and efficient manner.

Use Workloads

Use Workloads to manage resources that are shared across multiple Applications. For example, you can use Workloads to manage databases, domain names, and other resources that are shared across multiple Applications.

Workload constraints

Workload names must be unique within an Application. Workload names contain lowercase letters, numbers, and dashes. Workload names cannot contain spaces or special characters.

Command prerequisites

Set the following environment variables for the CLI and API commands shown throughout this page:

Variable Description
HUMANITEC_TOKEN The Humanitec token.
HUMANITEC_ORG The ID of the Humanitec Organization.
HUMANITEC_APP The ID of the Humanitec Application the Delta is in.
DELTA_ID The ID of the Deployment Delta to update.
WORKLOAD_ID The ID of the Workload to update.

To see existing Deployment Deltas for an Application and Environment, use this command:

humctl get delta


curl -s "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/deltas" \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  | jq

Manage Workloads

This section provides instructions for creating, duplicating, and deleting Workloads in Humanitec. A Workload is a specific instance of an Application that can be deployed and managed.

Create a Workload

  1. From the Applications overview , select the name of the Application and Environment where you’d like to create a Workload.
  2. Select a draft from the Draft deltas section, then select + Create new workload.
  3. Enter the following details and select Create workload.
    1. Enter a Workload name.
    2. (optional) Choose a Workload profile.

Add a workload to an existing Delta:

humctl update delta "${DELTA_ID}" add "/modules/${WORKLOAD_ID}" 'profile: humanitec/default-module'

More help can be found via humctl help update delta.

Add a workload to an existing Delta:

curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/deltas/${DELTA_ID}" \
  -X PATCH \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "modules": {
      "add": {
         "'"${WORKLOAD_ID}"'": {
            "profile": "humanitec/default-module"
         }
      }
    }
  }
]'

For more information, see: PatchDeploymentDelta API Documentation .

This action cannot be performed via Terraform as it involves updating a mutable object.

Results: Once the Workload has been created, it will appear in the Workloads section of your Application overview page. You can use the Workload to deploy and manage the selected draft.

Duplicate a Workload

  1. From the Applications overview , select the name of the Application and Environment where you’d like to create a Workload.
  2. Select a draft from the Draft deltas section.
  3. Select the Duplicate button on the Workload you want to duplicate.
  4. Enter the name of the duplicate Workload and click Duplicate.

Duplicating a workload in an existing Delta involves getting the existing workload out of the current Deployment Set and then adding it to the Delta. The procedure would be different if the workload to be cloned has not yet been deployed to the Environment.

  1. Fetch the existing workload from the current Deployment Set:

    humctl get set . -o json | jq ".object.modules.${WORKLOAD_ID}" > workload-to-clone.json

  2. Update the delta with the new cloned workload:

    humctl update delta "${DELTA_ID}" add "/modules/${NEW_WORKLOAD_ID}" "$(cat workload-to-clone.json)"

Where the following Environment variables are set:

Variable Example Description
NEW_WORKLOAD_ID new-workload The ID of the workload to add.

More help can be found via humctl help update delta.

This involves fetching the workload from the existing Deployment Set and extracting the workload out of it. It is a three step process:

  1. Determine the current Deployment Set from the current Environment
  2. Fetching the Deployment Set and extracting the workload.
  3. Patching the Delta with the new workload.

This action cannot be performed via Terraform as it involves updating a mutable object.

Results: You’ve duplicated an existing Workload.

Delete a Workload

  1. From the Applications overview , select the name of the Application and Environment where you’d like to remove a Workload.
  2. In a draft, select the trashcan icon on the Workload you’d like to remove.
  3. Select Delete to confirm.

Delete a workload from an existing Delta:

humctl update delta "${DELTA_ID}" remove "/modules/${WORKLOAD_ID}"

More help can be found via humctl help update delta.

Remove a workload from an existing Delta:

curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/deltas/${DELTA_ID}" \
  -X PATCH \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "modules": {
      "remove": [
         "'"${WORKLOAD_ID}"'"
      ]
    }
  }
]'

This action cannot be performed via Terraform as it involves updating a mutable object.

Results: You’ve removed a Workload.

Manage Cron Jobs

The cron job schedules feature enables you to define one or more schedules under which a Workload should run as a Kubernetes Cron Job. This can be useful for tasks that need to be performed regularly, such as backups, email notifications, and more.

Create Cron Job schedules

To create a cron job in the Humanitec platform, you must use the default-cronjob profile.

  1. From the Applications overview , select the name of the Application and Environment where you’d like to create a Workload.
  2. Select a draft from the Draft deltas section, then select a + Create new workload.
  3. Enter a name of a Workload and select the default-cronjob profile from the dropdown menu.
  4. Select Create workload and select your newly created Workload.
  5. Add a Container.
  6. Select + Add cronjob schedule and enter the following.
    1. Enter a name.
    2. Enter a cron job pattern.
    3. Choose a container.
    4. Enter commands to run and select Save.
    5. Enter arguments to pass to the command and select Save.
  7. Select Save changes.

  1. Create a new Deployment Delta:

    export DELTA_ID=$(humctl create delta -n "New CronJob" \
  --env development -o json | jq .metadata.id | tr -d "\"") \
  && echo $DELTA_ID

  2. Add a Workload and a schedule to the Deployment Delta:

    humctl update delta ${DELTA_ID} add /modules/${WORKLOAD_ID} '
profile: humanitec/default-cronjob
spec:
  containers:
    busybox:
      image: busybox:latest
  schedules:
    every-hour:
      containers:
        busybox:
          command:
          - "/bin/sh"
          args:
          - "-c"
          - "echo Hello World!"
      schedule: 15 * * * *
'

  3. Verify the result by displaying the details of the Deployment Delta:

    humctl get delta ${DELTA_ID} -o yaml

This action cannot be performed via Terraform as it involves updating a mutable object.

Results: Once the cron job schedule is saved, and the Deployment Delta deployed, the Workload runs according to the schedule you defined.

Manage containers

After creating a new Workload in your Application, you can add one or more containers. These can be based on images imported to Humanitec through a connected CI pipeline or pulled directly from an external registry not registered with Humanitec.

Container images can be registered with Humanitec. Continuous Integration (CI) pipelines can then notify Humanitec when a new build of a Container image becomes available. Humanitec tracks the image along with metadata about how it was built.

Create a container

Create a container in your Workload from the Workload Detail Screen.

  1. From the Applications overview , select the name of the Application and Environment where you’d like to create a container.
  2. Select an existing draft from the Draft deltas section or create a new one to make changes.
  3. Select the Workload you wish to create a container in.
  4. Under the Containers section, select the + Add container button.
  5. Choose one of the following options.
    1. (option 1) Filter by image.
      1. Filter or select an image.
      2. Select Select image.
    2. (option 2) Enter an image name.
      1. Enter the name of an image.
      2. Select Add image.
  6. Enter a container name and then select Create.

  1. Create a new Deployment Delta or use an existing one.

    To create a new Deployment Delta:

    export DELTA_ID=$(humctl create delta -n "New CronJob" \
  --env development -o json | jq .metadata.id | tr -d "\"") \
  && echo $DELTA_ID

    To use an existing Deployment Delta:

    # Show existing Deltas for the app
humctl get delta --app ${HUMANITEC_APP}

    # Set DELTA_ID to the ID of the relevant delta
export DELTA_ID=<id>

  2. Add a container to the Workload in the Deployment Delta.

    Note that this will replace an existing container already defined for the Workload. To add another container as a sidecar, see the section below.

    humctl update delta ${DELTA_ID} add /modules/${WORKLOAD_ID} '
profile: humanitec/default-module
spec:
  containers:
    mycontainer:
      image: myregistry/myimage
'

This action cannot be performed via Terraform as it involves updating a mutable object.

A valid image name is made up of slash-separated name components and can optionally be prefixed by a registry hostname or followed by a port. For example, myregistry:5000/postgres/httpd:1.0.

Add a sidecar container

Add a Sidecar Container to your workloads from the Workload Detail Screen.

  1. From the Application overview , select the name of the Application and Environment where you’d like to create a container.
  2. Select an existing draft from the Draft deltas section or create a new one to make changes.
  3. Under the Containers section, select the + Add container button.
    1. Select an image.
    2. Enter a name for the Container.
    3. Choose Create to create the Sidecar Container.

  1. Create a new Deployment Delta or use an existing one.

    To create a new Deployment Delta:

    export DELTA_ID=$(humctl create delta -n "New CronJob" \
  --env development -o json | jq .metadata.id | tr -d "\"") \
  && echo $DELTA_ID

    To use an existing Deployment Delta:

    # Show existing Deltas for the app
humctl get delta --app ${HUMANITEC_APP}

    # Set DELTA_ID to the ID of the relevant delta
export DELTA_ID=<id>

  2. Add the container to the Deployment Delta. Adjust the name newcontainer and the image as required.

    humctl update delta ${DELTA_ID} add /modules/${WORKLOAD_ID}/spec/containers/newcontainer '
image: myregistry/myimage
'

This action cannot be performed via Terraform as it involves updating a mutable object.

Update a container

Update a Container from the Workloads screen.

  1. From the Application overview , select the name of the Application and Environment where you’d like to update a container.
  2. Select an existing draft from the Draft deltas section or create a new one to make changes.
  3. Choose Workload and under the Containers section choose a Container, then select Change image.
  4. Choose one of the following options.
    1. (option 1) Filter by image.
      1. Filter or select an image.
      2. Select Select image.
    2. (option 2) Enter an image name.
      1. Enter the name of an image.
      2. Select Add image.

  1. Create a new Deployment Delta or use an existing one.

    To create a new Deployment Delta:

    export DELTA_ID=$(humctl create delta -n "New CronJob" \
  --env development -o json | jq .metadata.id | tr -d "\"") \
  && echo $DELTA_ID

    To use an existing Deployment Delta:

    # Show existing Deltas for the app
humctl get delta --app ${HUMANITEC_APP}

    # Set DELTA_ID to the ID of the relevant delta
export DELTA_ID=<id>

  2. Update the container. Adjust the container name and data as required.

    humctl update delta ${DELTA_ID} add /modules/${WORKLOAD_ID} '
profile: humanitec/default-module
spec:
  containers:
    mycontainer:
      image: myregistry/myimage
'

This action cannot be performed via Terraform as it involves updating a mutable object.

Results: You’ve successfully updated a Container.

Change a version

Change the image version of the Container.

  1. From the Applications overview , select the name of the Application and Environment where you’d like to update a container.
  2. Select an existing draft from the Draft deltas section or create a new one to make changes.
  3. Choose Workload and under the Containers section choose a Container, then select Change version.
  4. Select an image version.

You can also Archive an image by selecting the Archive from this window.

  1. Create a new Deployment Delta or use an existing one.

    To create a new Deployment Delta:

    export DELTA_ID=$(humctl create delta -n "New CronJob" \
  --env development -o json | jq .metadata.id | tr -d "\"") \
  && echo $DELTA_ID

    To use an existing Deployment Delta:

    # Show existing Deltas for the app
humctl get delta --app ${HUMANITEC_APP}

    # Set DELTA_ID to the ID of the relevant delta
export DELTA_ID=<id>

  2. Change the image of the target container in the Deployment Delta. Adjust the container name newcontainer and the image as required.

    humctl update delta ${DELTA_ID} add \
  /modules/${WORKLOAD_ID}/spec/containers/newcontainer/image \
  '"myregistry/myimage:1.2.3"'

This action cannot be performed via Terraform as it involves updating a mutable object.

Results: You’ve successfully updated a container version.

Remove a container

Remove a Container from the Workload.

  1. From the Applications overview , select the name of the Application and Environment where you’d like to remove a container.
  2. Select Make changes and choose a Workload.
  3. Under the Containers section, select a trash can icon next to the Container you want to remove.
  4. Select Delete to confirm.

Remove the container from the Deployment Delta. Adjust the container name newcontainer as required.

humctl update delta ${DELTA_ID} remove \
  /modules/${WORKLOAD_ID}/spec/containers/newcontainer

This action cannot be performed via Terraform as it involves updating a mutable object.

Results: You’ve successfully removed a container from a Workload.

Manage Resources

Manage resources you need for your Application. Resources can be things like databases or External Resources. The resources used can be configured individually for each Environment Type.

Humanitec takes care of generating the Ingress manifests that will be deployed in the cluster. To that, it needs a DNS resource. DNS resources can either be specific to a Workload or shared across an Application. In the previous example, shop.example.com should be specific to the Workload, as it is only used by frontend-workload. api.example.com is used by 2 Workloads, which means it makes sense for it to be a Shared Resource.

When you add a DNS Resource in Humanitec, you don’t actually specify the DNS name you want. You simply declare a dependency on a DNS resource. Your DevOps or Operations team will have configured Humanitec to generate an appropriate DNS name for you.

Add ingress

Ingresses are added to Workloads. The rules in an ingress refer to the current Workload.

  1. In Shared resources tab in a Draft, select Add shared resource.
  2. Add DNS, enter Resource ID, and then select Done.
  3. From the Ingress section in a Worklad, select the name of the ingress rule and choose from the following.
    1. Select a path type.
      1. Enter a path.
      2. Enter Port.
      3. Select Done.

  1. Add a Shared resource of type dns to the Deployment Delta.

    humctl update delta ${DELTA_ID} add /shared/dns '
class: default
type: dns
'

  2. Add an Ingress to the Workload. Adjust the actual ingress rules as required.

    humctl update delta ${DELTA_ID} add /modules/${WORKLOAD_ID}/spec/ingress '
rules:
  shared.dns:
    http:
      /:
        port: 8080
        type: prefix
'

This action cannot be performed via Terraform as it involves updating a mutable object.

Path rule types

The following table describes path types. Default and prefix are the most used paths.

Path rule type Description
Default All traffic not captured by other rules will be routed using this route.
Exact Only traffic with a path exactly matching this rule will be routed.
ImplementationSpecific The ingress controller defines how this is interpreted.
Prefix Any traffic with a path that starts with this pattern is routed.

Manage Resource dependencies

This section provides instructions for adding and removing resource dependencies from a Workload in Humanitec. A resource dependency is an external resource that is required for the Workload to function properly.

Add Resource dependencies

  1. From the Applications overview , select the name of the Application and Environment where you’d like to add resource dependencies.
  2. Select Make changes and choose a Workload.
  3. Under the Resource dependencies section, select Add resource dependency and choose the resource you want to add to the Workload.

Add a resource dependency to the Deployment Delta. Change the type from s3 to the desired type and adjust the name my-s3.

humctl update delta ${DELTA_ID} add /modules/${WORKLOAD_ID}/externals '
my-s3:
  type: s3
  class: default
'

This action cannot be performed via Terraform as it involves updating a mutable object.

Results: You have successfully added an external resource to a Workload. The required resource will be provisioned for each Environment when the workload is deployed.

Remove Resource dependencies

  1. From the Applications overview , select the name of the Application and Environment where you’d like to remove a resource dependency from.
  2. Select Make changes and choose a Workload.
  3. Under Resource dependencies, select the trash can icon and select Delete.

Remove the resource dependency. Adjust the id my-s3 to match the dependency.

humctl update delta ${DELTA_ID} remove \
  /modules/${WORKLOAD_ID}/externals/my-s3

This action cannot be performed via Terraform as it involves updating a mutable object.

Results: You have successfully removed an external resource from a Workload. The required resource will be removed from each Environment when the workload is deployed.

Manage files

Files in Humanitec are a subset of Kubernetes Projected volumes , they are injected into the file-system of the Container at Runtime. Files can be used to provide configuration for processes that cannot be configured via Environment Variables, or provide secret resources such as TLS certificates and keys.

On deployment, Humanitec collects Files defined for containers in a Workload into either a configMap  or a secret  Kubernetes object. They are then inserted into a container’s file-system through a Projected Volume .

Full paths and permission mode

Files are inserted into the Container’s file-system at a particular Path and with a particular permission mode.

The path must start with / and cannot end with /. It must be a valid Unix style file path.

The Permission Mode defines the permission bits on the file in the file-system. Unix like systems (including Linux) define 3 possible sets of permissions for a file:

  • Permissions for the owner of the File
  • Permissions for the group that owns the File
  • Permissions for all users on the system

Each of these permissions can be any combination of Read, Write, or Execute. The block of permissions is traditionally written as 3 Octal digits with each digit representing 3 bits for Read, Write, and Execute for each of the permissions. You can use tools like chmod-calculator.com  to help you calculate the Octal mode for a file. Humanitec defaults to 0777 which allows Read, Write and Execute on all files.

Using Placeholders

As with Environment Variables, any number of Placeholders (from Values, Resources, Contexts, or even other Workloads) can be used in Files.

Secrets

Sometimes a file needs to contain a sensitive value that should not be visible to developers. An example of this would be database credentials. Secrets should be stored as shared Values and Secrets and then referenced in a file using a Placeholder. If the content of a Placeholder is a Secret, Humanitec automatically converts the entire value into a Secret.

Create files

  1. From the Applications overview , select the name of the Application and Environment where you’d like to add a File.
  2. Select Make changes. Choose the Workload and then the Container.
  3. Under Files section, select + Add Files.
    1. In the Path field, provide the full-path for where the file should be located in the Container’s filesystem.
    2. Provide a Permission Mode as described above in the Mode field.
    3. Define your file content in the multi-line textbox, setting the content-type with the dropdown to adjust the syntax highlighting as needed.
  4. To save your File, choose Save.

Add the file specification to the target container. Adjust the container name mycontainer and the file data as required.

humctl update delta ${DELTA_ID} add \
/modules/${WORKLOAD_ID}/spec/containers/mycontainer/files '
/www/my.conf:
  mode: "0644"
  value: |-
    Sample multiline content
    of my file
'

Results: You’ve successfully created a file.

Configure Workload deployment

Configure the behavior of Workload deployments. This includes defining how a deployment can be considered successful and running jobs before, during, or after the main deployment has occurred.

Property Type Default Description
when string deploy Defines the stage at which the Workload should be deployed. Can be one of before, deploy, or after.
success string deployed Defines the success criteria for the workload. Can be one of:
  • deployed: the manifests were successfully updated in the cluster
  • available: all pods are in a ready state.
  • complete: a job has completed successfully
timeout integer 300 Defines the maximum time in seconds to wait for the success condition to be met.

Currently not available in the Portal.

Add the required behavior to your Workload, adjusted as required.

humctl update delta ${DELTA_ID} \
add /modules/${WORKLOAD_ID}/deploy '
success: available
timeout: 150
'


curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/deltas/${DELTA_ID}" \
  -X PATCH \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '[{
  "modules": {
	  "update" : {
      "'"${WORKLOAD_ID}"'": [{
        "op": "add",
        "path": "/deploy",
        "value": {
          "success": "available",
          "timeout": 150
        }
      }]
    }
  }
}]'

This action cannot be performed via Terraform as it involves updating a mutable object.

Set and Deltas

Shared Values