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.

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'

Where the following Environment variables are set:

Variable Example Description
DELTA_ID 65f9fa76913b The ID of the Delta to add the workload to.
WORKLOAD_ID new-workload The ID of the workload to add.

Add a workload to an existing Delta:

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

Where the following environment variables are set:

Variable Example Description
HUMANITEC_TOKEN lsakdjhcals A Humanitec token of a user with at least Owner role on the Application.
HUMANITEC_ORG my-org The Humanitec organization the Application is in.
APP_ID my-app The ID of the App. Must be lower case letters, numbers or dashes. Cannot start or end with a dash.
DELTA_ID 65f9fa76913b The ID of the Delta to add the workload to.
WORKLOAD_ID new-workload The ID of the workload to add.

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
DELTA_ID 65f9fa76913b The ID of the Delta to add the workload to.
WORKLOAD_ID new-workload The ID of the workload to add.
NEW_WORKLOAD_ID new-workload The ID of the workload to add.

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}"

Where the following Environment variables are set:

Variable Example Description
DELTA_ID 65f9fa76913b The ID of the Delta to add the workload to.
WORKLOAD_ID new-workload The ID of the workload to add.

Remove a workload from an existing Delta:

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

Where the following environment variables are set:

Variable Example Description
HUMANITEC_TOKEN lsakdjhcals A Humanitec token of a user with at least Owner role on the Application.
HUMANITEC_ORG my-org The Humanitec organization the Application is in.
APP_ID my-app The ID of the App. Must be lower case letters, numbers or dashes. Cannot start or end with a dash.
DELTA_ID 65f9fa76913b The ID of the Delta to add the workload to.
WORKLOAD_ID new-workload The ID of the workload to add.

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.

Instructions coming soon.

Instructions coming soon.

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

Results: Once the cron job schedule is saved, 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. Under the Containers section, select the + Add container button.
  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.
  5. Enter a container name and then select Create.

Instructions coming soon.

Instructions coming soon.

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.

Instructions coming soon.

Instructions coming soon.

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.

Instructions coming soon.

Instructions coming soon.

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.

Instructions coming soon.

Instructions coming soon.

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.

Instructions coming soon.

Instructions coming soon.

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.

Instructions coming soon.

Instructions coming soon.

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.

Instructions coming soon.

Instructions coming soon.

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.

Instructions coming soon.

Instructions coming soon.

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.

CLI instructions coming soon.

API instructions coming soon.

Terraform instructions coming soon.

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 Web UI.

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

Where the following Environment variables are available:

Variable Description
HUMANITEC_TOKEN The Humanitec API Key
HUMANITEC_CONTEXT The Context that the delta is in. Must be a minimum of org and app.
DELTA_ID The ID of the Delta to update
WORKLOAD_ID The ID of the Workload to update.

curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/apps/${APP_ID}/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"
        }
      }]
    }
  }
}]'

Where the following Environment variables are available:

Variable Description
HUMANITEC_TOKEN The Humanitec API Key
HUMANITEC_ORG The ID of the Humanitec Organization.
APP_ID The ID of the Humanitec Application the delta is in.
DELTA_ID The ID of the Delta to update
WORKLOAD_ID The ID of the Workload to update.

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

Top