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

From the Applications overview, select the name of the Application and Environment where you’d like to create a Workload.
Select a draft from the Draft deltas section, then select + Create new workload.
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.

  <div class="w-100"> More help can be found via <code>humctl help update delta</code>.</div>

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.

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

From the Applications overview, select the name of the Application and Environment where you’d like to create a Workload.
Select a draft from the Draft deltas section.
Select the Duplicate button on the Workload you want to duplicate.
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.

This involves the jq utility.

Fetch the existing workload from the current Deployment Set:

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

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.

  <div class="w-100"> More help can be found via <code>humctl help update delta</code>.</div>

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

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

For more information, see:

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

Results: You’ve duplicated an existing Workload.

Delete a Workload

From the Applications overview, select the name of the Application and Environment where you’d like to remove a Workload.
In a draft, select the trashcan icon on the Workload you’d like to remove.
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.

  <div class="w-100"> More help can be found via <code>humctl help update delta</code>.</div>

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.

For more information, see: PatchDeploymentDelta API Documentation

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.

From the Applications overview, select the name of the Application and Environment where you’d like to create a Workload.
Select a draft from the Draft deltas section, then select a + Create new workload.
Enter a name of a Workload and select the default-cronjob profile from the dropdown menu.
Select Create workload and select your newly created Workload.
Add a Container.
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.
Select Save changes.

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.

From the Applications overview, select the name of the Application and Environment where you’d like to create a container.
Select an existing draft from the Draft deltas section or create a new one to make changes.
Under the Containers section, select the + Add container button.
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.
Enter a container name and then select Create.

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.

From the Application overview, select the name of the Application and Environment where you’d like to create a container.
Select an existing draft from the Draft deltas section or create a new one to make changes.
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.

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

Update a container

Update a Container from the Workloads screen.

From the Application overview, select the name of the Application and Environment where you’d like to update a container.
Select an existing draft from the Draft deltas section or create a new one to make changes.
Choose Workload and under the Containers section choose a Container, then select Change image.
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.

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.

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

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

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.

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

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.

In Shared resources tab in a Draft, select Add shared resource.
Add DNS, enter Resource ID, and then select Done.
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.

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

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

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

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

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.

Files differ from Volumes in that they cover specific files rather than directories. Files also reset on every deployment. You should use Files for things related to configuration that might need to be changed by developers. You should use Volumes for things related to data that the app creates or consumes.

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

From the Applications overview, select the name of the Application and Environment where you’d like to add a File.
Select Make changes. Choose the Workload and then the Container.
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.
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.

The Path and Mode are required Fields. Path must start with /.

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.

When specifying before or after, ensure the Workload terminates, for example by using a Kubernetes Job. If the Workload does not terminate, the deployment process may hang.

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.

Workloads

Use Workloads #

Workload constraints #

Manage Workloads #

Create a Workload #

Duplicate a Workload #

Delete a Workload #

Manage Cron Jobs #

Create Cron Job schedules #

Manage containers #

Create a container #

Add a sidecar container #

Update a container #

Change a version #

Remove a container #

Manage Resources #

Add ingress #

Path rule types #

Manage Resource dependencies #

Add resource dependencies #

Remove Resource dependencies #

Manage files #

Full paths and permission mode #

Using Placeholders #

Secrets #

Create files #

Configure Workload deployment #

Use Workloads

Workload constraints

Manage Workloads

Create a Workload

Duplicate a Workload

Delete a Workload

Manage Cron Jobs

Create Cron Job schedules

Manage containers

Create a container

Add a sidecar container

Update a container

Change a version

Remove a container

Manage Resources

Add ingress

Path rule types

Manage Resource dependencies

Add resource dependencies

Remove Resource dependencies

Manage files

Full paths and permission mode

Using Placeholders

Secrets

Create files

Configure Workload deployment