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.
- Enter a Workload name.
- (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. |
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.
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. |
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.
- Enter a name.
- Enter a cron job pattern.
- Choose a container.
- Enter commands to run and select Save.
- Enter arguments to pass to the command and select Save.
- 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.
- 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.
- (option 1) Filter by image.
- Filter or select an image.
- Select
Select image
.
- (option 2) Enter an image name.
- Enter the name of an image.
- Select
Add image
.
- (option 1) Filter by image.
- 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.
- 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.- Select an image.
- Enter a name for the Container.
- 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.
- 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.
- (option 1) Filter by image.
- Filter or select an image.
- Select
Select image
.
- (option 2) Enter an image name.
- Enter the name of an image.
- Select
Add image
.
- (option 1) Filter by 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.
- 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 theArchive
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.
- 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.
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.
- Select a path type.
- Enter a path.
- Enter Port.
- Select Done.
- Select a path type.
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
- 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.
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.
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
- 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.
- In the Path field, provide the full-path for where the file should be located in the Container’s filesystem.
- Provide a Permission Mode as described above in the Mode field.
- 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.
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:
|
timeout |
integer |
300 |
Defines the maximum time in seconds to wait for the success condition to be met. |
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.