Features

Workload Profiles are made up of features. Each feature represents a set of functionality that can be configured for the Workload.

Humanitec provides a set of features that can be used across different Workload Profiles.

annotations #

The annotations feature defines Annotations 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 annotations on the Pod.

Description #

Annotations are defined as a map with keys and values.

Keys are made up of an optional prefix followed by an 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.

Example #

{
  "owner": "pat",
  "humanitec.com/version": "v9.2.4"
}

containers #

The containers feature allows containers to the added to a workload.

Description #

The top level of the container feature is a map with user provided IDs as keys and container objects as values. Each container object has a set of properties:

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.

Example #

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

Probes #

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

The following properties are available in all Probes:

command #

Example #

{
  "command": [
    "bash",
    "-c",
    "/app/is_alive.sh"
  ],
  "type": "command"
}

http #

Example #

{
  "headers": {
    "Cache-Control": "no-store"
  },
  "path": "/alive",
  "port": 8080,
  "type": "http"
}

tcp #

Example #

{
  "port": 8080
}

Container Resources #

Specify the minimum and maximum resources required for this container. Pods will not be scheduled unless the minimum requests 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:

Example #

{
  "cpu": "0.250",
  "memory": "256Mi"
}

Environment 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.

Example #

{
  "MY_ENV_VAR": "Hello World!"
}

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 so should be referenced via their resource ID. (e.g. shared.nfs-share). Other volume types can be reference via the definition in the volumes section. (e.g. volumes.common-dir)

Example #

{
  "/shared/common": {
    "id": "volumes.common-dir",
    "read_only": false,
    "sub_path": "/cache"
  }
}

Example #

{
  "my-container": {
    "args": [
      "--run",
      "webserver"
    ],
    "command": [
      "node",
      "index.js"
    ],
    "files": {
      "/app/default.config": {
        "mode": "0644",
        "value": "[config]\nkey=value"
      }
    },
    "id": "sample-service",
    "image": "registry.humanitec.io/public/sample-service:1.2.0",
    "liveness_probe": {
      "command": [
        "bash",
        "-c",
        "/app/is_alive.sh"
      ],
      "type": "command"
    },
    "readiness_probe": {
      "headers": {
        "Cache-Control": "no-store"
      },
      "path": "/alive",
      "port": 8080,
      "type": "http"
    },
    "resources": {
      "limits": {
        "cpu": "0.250",
        "memory": "256Mi"
      },
      "requests": {
        "cpu": "0.025",
        "memory": "64Mi"
      }
    },
    "variables": {
      "MY_ENV_VAR": "Hello World!"
    },
    "volume_mounts": {
      "/shared/common": {
        "id": "volumes.common-dir",
        "read_only": false,
        "sub_path": "/cache"
      }
    }
  }
}

ingress #

The ingress feature defines how the ingress routing should be configured for the workload. The schema is similar but not the same as the that of the IngressSpec object.

Description #

The top level of the ingress feature only contains the property rules. This contains a map of DNS resource IDs to rule objects.

The resource IDs must be specified using the full ID - e.g. shared.api-dns or externals.www-dns.

As with the current IngressSpec object, only HTTP rules are supported. Therefore for each DNS resource key, there is a value of an object with a single property of http and a value of a map of HTTP rules.

The map of rules has keys of HTTP paths. These are interpreted based on the path type. Path types can be as follows:

The rule supports the following properties:

Example #

This example shows an ingress configuration for a workload that implements part of a shared API. It also exposes a diagnostic endpoint on a different DNS name.

{
  "rules": {
    "shared.api-dns": {
      "http": {
        "/customers": {
          "port": 8080,
          "type": "Prefix"
        },
        "/profiles": {
          "port": 8080,
          "type": "Prefix"
        }
      }
    },
    "externals.diagnostics-dns": {
      "http": {
        "*": {
          "port": 14781,
          "type": "default"
        }
      }
    }
  }
}

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 an 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]),
• could contain dashes (-), underscores (_), dots (.), and alphanumerics between.

Example #

{
  "owner": "pat",
  "humanitec.com/type": "dev-eu-01"
}

replicas #

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.

schedules #

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

Description #

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

The top level is a Map of schedule objects. The Key must be a valid Humanitec ID. It is an error for the Map to be empty.

The schedule object has the following properties:

Example #

This example shows schedules for a CronJob with one container with the id main-container. The schedules are daily and every 6 hours. Each schedule runs a different command.

{
  "daily-run": {
    "schedule": "0 23 * * *",
    "containers": {
      "main-container": {
        "command": [
          "node",
          "daily-cron.js"
        ]
      }
    }
  },
  "6-hour-run": {
    "schedule": "15 1,7,13,19 * * *",
    "containers": {
      "main-container": {
        "args": [
          "--hours",
          "6"
        ]
      }
    }
  }
}

service-account #

The service-account feature defines the Kubernetes Service Account that Pods in the workload should run as.

Description #

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

Example #

"data-access-service-account"

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:

Example #

This example shows an service configured with 2 port, one exposes port 8080 and maps to port 3001 on the container. The other listens on 90245 expecting a UDP connection.

{
  "www": {
    "service_port": 8080,
    "container_port": 3001
  },
  "stream": {
    "service_port": 90245,
    "protocol": "UDP"
  }
}

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:

Example #

This example shows an emptyDir with a 1GB size limit.

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