Resource Definitions

A Resource Definition defines how and when a Resource should be provisioned. It is made up of the Resource Type, Resource Drivers and its inputs, along with a set of Matching Criteria to define when to select the Resource Definition. Resource Definitions are generally created and managed by the Platform Team.

A Resource Definition holds the following:

Parameter Description
Resource Type The type of resource that the Resource Definition provisions.
Resource Driver The ID of the Resource Driver to use when provisioning the resource.
Driver Inputs Driver specific inputs that are taken by the Driver alongside the Resource inputs.
Matching Criteria The criteria used to select which Resource Definition of a specific Resource Type.

Driver inputs

The Resource Definition defines Driver Inputs that are passed to the Resource Driver that performs the provisioning of a resource. The schema of the Driver Inputs depends on the driver. For example, provisioning a dns resource with the humanitec/dns-cloudflare Driver requires the Cloudflare Zone ID and the parent domain to be specified while the humanitec/dns-wildcard Driver only requires the parent domain.

The Driver Inputs can make use of Placeholders to insert parts of the Resource Context.

Matching criteria

Matching Criteria provide a way for Humanitec to select a Resource Definition for provisioning a resource in a given Resource Context. Each Resource Definition can have 0 or more Matching Criteria associated with it. Each of the Matching Criteria defines 0, 1 or more parts of the context that must match in order for a Resource Definition to be selected. When selecting with Matching Criteria, the most specific one is selected. In general, this means if all the Matching Criteria fully matching the context, the Matching Criteria Rule with the most specific element filled is chosen. If there is a tie, the next most specific elements are compared and so on until one is chosen.

A Resource Definition with no Matching Criteria will not be considered.

Criteria specificity

In general, the parts of the matching criteria are in order from least specific to most specific as follows:

Environment Type < Application ID < Environment ID < Resource ID < Resource Class

This means that Matching Criteria containing a Resource ID will always be more specific than any Matching Criteria that does not contain a Resource ID.

Mathematically, the specificity of Matching Criteria can be calculated by summing together weights for each part of the Matching Criteria:

Part Weight
Environment Type 1
Application ID 2
Environment ID 4
Resource ID 8
Resource Class 16

An empty Matching Criteria would score 0, one containing just an Environment ID would score 4 and one containing an Application ID and Environment Type would score 3.

The Matching Criteria with the highest total weight are the most specific.


Consider an Application called awesome-app with multiple Environments of type development. There is a shared environment called dev used by all developers and multiple “PR” environments which are created automatically when a PR is created in GitHub. The dev environment should be accessible via a stable DNS name of while the preview environments should be available on randomly generated subdomains such as or

Two Resource Definitions of type dns are created:

  • static-dev-dns - always returns the same DNS name of
  • random-dev-dns - generates a random subdomain

They have the following Matching Criteria:

Resource Definition Environment Type Application ID Environment ID Resource ID Resource Class
static-dev-dns awesome-app dev shared.api-dns default
random-dev-dns development awesome-app shared.api-dns default

When a deployment occurs in the dev environment, Humanitec will attempt to provision a dns resource with ID shared-api-dns. Looking at the Matching Criteria for Resource Definitions of type dns it will return static-dev-dns and random-dev-dns. In this case, the static-dev-dns would be chosen because its Matching Criteria are more specific.

When a deployment occurs in a PR environment, only the random-dev-dns Resource Definition would be returned.

Manage Resource Definitions

Resource Definitions can be managed via the UI, CLI, API and using the Humanitec Terraform provider.

All actions involving Resource Definitions require the user to have the Administrator role in the Organization.

  1. Click the Resource Management menu item from the left-hand navigation to open the Resource Management screen.

  2. Select + Add resource definition, on the top left of the screen.

  3. Select the Resource Type for the Resource Definition you want to create in the dialog.

  4. Select the appropriate Driver from the list.

  5. Supply the Driver ID any additional inputs that are required by the Driver.

  6. Select Add, in the bottom right of the dialog.

  1. Create a file defining the Resource definition you want to create:
cat << EOF > my-def.yaml
kind: Definition
  id: example-ns-def
  type: k8s-namespace
  name: k8s-namespace
  driver_type: humanitec/echo
      namespace: \${}-\${}
  1. Use the humctl create command to create the resource definition in the organization defined by your configured context:
humctl create -f my-def.yaml

curl "${HUMANITEC_ORG}/resources/defs" \
  -X POST \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "example-ns-def",
  "type": "k8s-namespace",
  "driver_type": "humanitec/echo",
  "driver_inputs": {
    "values": {
      "namespace": "${}-${}"

Where the following environment variables are set:

Variable Example Description
HUMANITEC_TOKEN lsakdjhcals A Humanitec token of a user with at least Developer permission on the Application.
HUMANITEC_ORG my-org The Humanitec organization the Application is in.

resource "humanitec_resource_definition" "example-ns-def" {
  driver_type = "humanitec/echo"
  id          = "example-ns-def"
  name        = "example-ns-def"
  type        = "k8s-namespace"

  driver_inputs = {
    values = {
      "namespace" = "$${}-$${}"

Manage Resource Definitions by selecting Resources from the main navigation menu.

Create definitions for Resources

  1. On the Resources Management screen, assuming the Resource Type you’re looking for is not already in the hot-list, click Show all resources.
  2. From the grid, select the Resource Type that you need to create a Definition for.
  3. In the modal dialog, fill out the id field and select the appropriate Driver from the list.
  4. Supply any additional inputs that are required by the Driver.
  5. Select Create.

Delete definitions for Resources

  1. On the Resources Management screen, select the .. at the end of the row of the Resource Definition that you wish to delete.
  2. Select Delete.
  3. In the modal dialog, choose Delete to confirm.

Using secret references

You can use secret references to read secrets from secret stores, and pass them to Drivers as driver_inputs. Go here to see examples.