Definitions
Resource Definitions
A Resource Definition defines how and when a Resource should be provisioned. It defines the the Resource Driver 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
They 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 take 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 perform the provisioning of a resource. The schema of the Driver Inputs depend 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.

Resource Context

Each resource is provisioned in a specified context. This context is made up of the following 3 elements:
  • Application ID
  • Environment ID
  • Resource ID
When combined with the Resource Type, the context uniquely defines a provisioned resource. This allows discrimination between different active instances of the same resource in different Applications and Environments.

Example

A developer has added a shared Resource Dependency on a resource of type dns and given it the ID api-dns. (This makes its fully qualified resource ID shared.api-dns.) If there are three environments (development, staging and production) then there will be three instances of this resource - one in each environment. Each active resource will have the same Application ID and Resource ID, but they will have different Environment IDs. Therefore they each have a unique context:
Application ID
Environment ID
Resource ID
awesome-app
development
shared.api-dns
awesome-app
staging
shared.api-dns
awesome-app
production
shared.api-dns

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

Criteria Specificity

In general, the parts of the matching criteria are order from least specific to most specific as follows:
Environment Type < Application ID < Environment ID < Resource ID
This means that a 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 a 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
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 is 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:
Resource Definition
Environment Type
Application ID
Environment ID
Resource ID
static-dev-dns
awesome-app
dev
shared.api-dns
random-dev-dns
development
awesome-app
shared.api-dns
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 it's Matching Criteria is more specific.
When a deployment occurs in a PR environment, only the random-dev-dns Resource Definition would be returned.
Last modified 5mo ago
Copy link
On this page
Driver Inputs
Resource Context
Example
Matching Criteria
Criteria Specificity
Example