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 | |
Driver Inputs | |
Matching Criteria | The criteria used to select which Resource Definition of a specific Resource Type. |
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.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.
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 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.
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.
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 ofdev-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 8mo ago