Active Resources

Active Resources are provisioned and active instances of a resource. Each Environment that has been deployed to has a set of Active Resources.

Lifecycle of a Resource #

Resources are provisioned at deployment time. To provision a resource, the Platform Orchestrator identifies the Resource Definition that matches the Resource Dependency and uses the Driver specified in the Resource Definition to provision the resource.

Resources are deprovisioned, under the following conditions:

• a new resource with the same context is provisioned or
• the environment the resource provisioned in is deleted.

This means it is not sufficient to remove a resource dependency in order for the resource to be deprovisioned. Specifically, removing a resource from the Score file and re-deploying the file it will not deprovision the resource. This behavior allows for rollbacks to previous deployments without losing state in stateful resources such as an Amazon S3 buckets or Databases.

GUResID #

Each Active Resource receives a permanent, non-semantic Globally Unique Resource ID (GUResID) to identify the Resource throughout its lifecycle. This ID is guaranteed to be unique and consistent for future provisioning of this Resource. It is used by Drivers to track state .

The GUResID is a string of hexadecimal digits, e.g. 3c0a194814284345e330544f88798e83992468e2.

You can query the GUResID inside Resource Definitions using a Placeholder .

For an active Deployment, you can observe the GUResID in the property .status.gu_res_id of each Resource in the output of this CLI command:

humctl get active-resources -o yaml

Resource ID #

The Resource ID (resID) is a human-readable, hierarchical name for an Active Resource. Example Resource IDs are:

• base-env
• shared.my-dns
• modules.my-workload.externals.my-dns

A Resource ID is not necessarily unique within an Environment.

You can query the Resource ID inside Resource Definitions using the context.res.id Placeholder .

For a Deployment, the Resource ID is shown in the Humanitec Portal on each Resource in the display of the Resource Graph. You can also observe the Resource ID in the property .metadata.res_id of each Resource in the output of this CLI command:

humctl get active-resources -o yaml

The shape of the Resource ID depends on usage of the Active Resource. You will find more details and examples in the sections below.

Resource IDs for workload resources #

A Resource of type workload will have a Resource ID of modules.<workload-name>.

Example #

This Score file defining the Workload named my-workload will result in an Active Resource of type workload and a Resource ID of modules.my-workload.

apiVersion: score.dev/v1b1
metadata:
  name: my-workload
...

Resulting Resource Graph:

flowchart LR
    workload(type: workload<br/>Resource ID: modules.my-workload)

Resource IDs for implicit Resources #

A Resource created due to being of an implicit Resource Type will have a Resource ID of <resource-type>.

Example #

The Active Resource of type base-env will have the Resource ID base-env.

Resulting Resource Graph:

flowchart LR
  workload(type: workload<br/>Resource ID: modules.my-workload)
  base-env(type: base-env<br/>Resource ID: base-env)

Resource IDs for private dependencies #

A Private dependency of a Workload will have a Resource ID of modules.<workload-name>.externals.<resource-name>.

Example #

Adding a resource named users-route of type route to the Score file will result in an Active Resource of type route and a Resource ID of modules.my-workload.externals.users-route.

apiVersion: score.dev/v1b1
metadata:
  name: my-workload
...
resources:
  users-route:
    type: route
...

Resulting Resource Graph:

flowchart LR
  workload(type: workload<br/>Resource ID: modules.my-workload) --> route(type: route<br/>Resource ID: modules.my-workload.externals.users-route)

Resource IDs for shared dependencies #

A Shared dependency of a Workload will have a Resource ID of shared.<resource-id>.

Example #

Adding a resource with an id of dns-common of type dns to the Score file will result in an Active Resource of type route and a Resource ID of shared.dns-common. Using the same id in another Score file deployed into the same Environment will reference the same Active Resource.

# Score file 1
apiVersion: score.dev/v1b1
metadata:
  name: my-workload
...
resources:
  my-dns:
    type: dns
    id: dns-common
...

# Score file 2
apiVersion: score.dev/v1b1
metadata:
  name: my-other-workload
...
resources:
  the-same-dns:
    type: dns
    id: dns-common
...

Resulting Resource Graph:

flowchart LR
  workload1(type: workload<br/>Resource ID: modules.my-workload) --> shared(type: dns<br/>Resource ID: shared.dns-common)
  workload2(type: workload<br/>Resource ID: modules.my-other-workload) --> shared

Resource IDs for Resource references or co-provisioning #

A Resource created through a Resource reference or co-provisioning inside a Resource Definition will have the same Resource ID as the referencing Resource by default. The Resource ID is propagated.

The Propagate ID Resource Graph pattern demonstrates Resource ID propagation.

Exception: if the Resource reference or co-provisioning specifies an ID, then the Resource will have that Resource ID.

Example #

This Resource Definition of type s3 contains Resource references to config Resources without and with an ID, as well as a Resource co-provisioning without an ID.

Its own Resource ID as a private dependency of the Workload my-workload is modules.my-workload.externals.bucket. This ID will be propagated to the first referenced Resource as well as to the co-provisioned Resource because no ID is specified for both.

The second referenced Resource will have the ID my-config as specified in the reference descriptor.

# Score file
apiVersion: score.dev/v1b1
metadata:
  name: my-workload
...
resources:
  bucket:
    type: s3
...

# Resource Definition
apiVersion: entity.humanitec.io/v1b1
kind: Definition
...
entity:
  type: s3
  driver_inputs:
    values:
      resource_ref_without_id: ${resources.config.outputs.some-value}
      resource_ref_with_id: ${resources.['config#my-config'].outputs.some-other-value}
  ...
  provision:
    aws-policy: {}

Resulting Resource Graph:

flowchart LR
  workload(type: workload<br/>Resource ID: modules.my-workload) --> s3(type: s3<br/>Resource ID: modules.my-workload.externals.bucket)
  s3 --> config1(type: config<br/>Resource ID: modules.my-workload.externals.bucket) -.- commentConfig1(From<br/>Resource reference<br/>without ID):::comment
  s3 --> config2(type: config<br/>Resource ID: my-config) -.- commentConfig2(From<br/>Resource reference<br/>with ID):::comment
  awsPolicy(type: aws-policy<br/>Resource ID: modules.my-workload.externals.bucket) -.- commentAwsPolicy(From<br/>co-provisioning<br/>without ID):::comment

  classDef comment stroke-width:0px,fill:#FFFFFF00

Resource descriptor #

The Resource descriptor extends the Resource ID by prepending its type and class to uniquely identify an Active Resource within an Environment.

The Resource descriptor format is <type>.<class>#<resID>. Example Resource descriptors are:

• dns.default#modules.my-workload.externals.my-dns
• postgres.basic#modules.my-module.externals.my-db
• s3.small#shared.bucket

Resources referenced via the same Resource Descriptor in the Environment will be the same Resource.

Resource Descriptors are used throughout the Platform Orchestrator to describe Resources in logs and error messages.

As a Platform Engineer, you use Resource descriptors when constructing your Resource Graph through Resource references or co-provisioning .

Listing #

By Environment #

The Active Resources deployed in an Environment can be viewed by anyone with at least Viewer permission on the Application that the Environment is in.

• Web UI
• CLI
• API
• Terraform

humctl get active-resources

curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/envs/${HUMANITEC_ENV}/resources" \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}"

By Resource Definition #

The Active Resources provisioned via a particular Resource Definition can be viewed by any user with the Administrator role in the organization.

• Web UI
• CLI
• API
• Terraform

humctl api get /orgs/${HUMANITEC_ORG}/resources/defs/${RES_DEF_ID}/resources

curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/resources/defs/${RES_DEF_ID}/resources" \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}"

Deprovisioning #

Active Resources can be explicitly deprovisioned or deleted without the Environment they have been provisioned in being deleted. This can only be done by users who have the Administrator role in the Organization.

Deprovisioning an Active Resource that is in use in an Environment can have unintended consequences of failure of the application running in the environment or failure of deprovisioning other resources that depend on it. No checks are made by the Platform Orchestrator when directly deprovisioning an Active Resource.

The current behavior when deprovisioning an Active Resource is as follows:

• In Legacy mode : the real-world resource is deleted
• In Direct mode : the real-world resource is NOT deleted

• Web UI
• CLI
• API
• Terraform

humctl api delete "/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/envs/${HUMANITEC_ENV}/resources/${RES_TYPE}/${RES_ID}?force=true"

curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/envs/${HUMANITEC_ENV}/resources/${RES_TYPE}/${RES_ID}?force=true" \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}"