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.

Several pre-defined default Resource Definitions are available by default in all Organizations. These definitions are managed by Humanitec but can be enabled or disabled as needed.

A Resource Definition holds the following:

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:

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.

Example #

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 dev-api.awesome.app while the preview environments should be available on randomly generated subdomains such as fjs92.awesome.app or 4ij76s.awesome.app.

Two Resource Definitions of type dns are created:

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

They have the following Matching Criteria:

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.

• Web UI
• CLI
• API
• Terraform

cat << EOF > my-def.yaml
apiVersion: entity.humanitec.io/v1b1
kind: Definition
metadata:
  id: example-ns-def
entity:
  type: k8s-namespace
  name: k8s-namespace
  driver_type: humanitec/echo
  driver_inputs:
    values:
      namespace: \${context.app.id}-\${context.env.id}
EOF

humctl create -f my-def.yaml

curl "https://api.humanitec.io/orgs/${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": "${context.app.id}-${context.env.id}"
    }
  }
}'

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" = "$${context.app.id}-$${context.env.id}"
    }
  }
}

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.

Default Resource Definitions #

The Humanitec Platform Orchestrator provides a collection of default Resource Definitions for commonly provisioned resources. These are available by default in all organizations and do not require explicit matching criteria as they will match any supported resources that don’t have a custom Resource Definition and matching criteria.

Default Resource Definitions are available for:

• base-env - No special behavior.
• workload - No special behavior.
• k8s-namespace - Generates a random namespace name.
• ingress - Provisions a Kubernetes networking.k8s.io/v1 Ingress using the Ingress driver.
• logging - Defaults to Kubernetes logging.
• route - See Routes for more information on how Route resources are handled.
• dns - Provisions a new random DNS subdomain of the newapp.io domain using the newapp-io-dns Driver .
• tls-cert - Provides a default TLS certificate secret for the newapp.io domain using the newapp-io-tls Driver .
• (Deprecated) k8s-cluster - Provisions an ephemeral and temporary Kubernetes cluster credential.
• (Deprecated) postgres - Provisions an ephemeral and temporary Postgres database.

The Default Resource Definitions marked as (Deprecated) cannot be used when using the Humanitec Operator . They work in Legacy mode only. Their use is strongly discouraged.

Default Resource Definitions can be disabled through either the Web UI or CLI. Note that this will cause any existing active resources that use this definition to be re-provisioned on the next deployment.

• Web UI
• CLI

humctl api PUT /orgs/${HUMANITEC_ORG}/resources/defs/default-humanitec-dns/criteria --data '[]'

humctl api PUT /orgs/${HUMANITEC_ORG}/resources/defs/default-humanitec-dns/criteria --data '[{"class": "default"}]'

Examples #

• See our example collection of Resource Definitions show their usage for a wide range of use cases.
• See how to add common infrastructure Resources to your platform based on our Resource Packs .