Active Resources

Active Resources represent the concrete resources provisioned for an Environment within the Platform Orchestrator.

“Provisioning” means successfully executing the Resource Definition that matches a Resource Dependency in the Resource Graph during a Deployment by using the specified Driver.

Depending on the Driver, provisioning may mean creating one or more real-world objects such as a database or namespace, or just creating a representation of an existing real-world object e.g. using the Echo Driver.

Lifecycle of a Resource

Creating

An Active Resource is created in the course of a Deployment into an Environment.

The Platform Orchestrator adds a node to the Resource Graph due to some Resource Dependency
The Platform Orchestrator tries to provision the resource using the Driver specified in the Resource Definition
- If provisioning succeeds, an Active Resource is created
- If provisioning fails, the resource node is still shown in the Graph, but no Active Resource is created. It may be created through a subsequent Deployment once provisioning is successful

You can query Active Resources for an Environment, see listing.

Subsequent deployments

The Platform Orchestrator will try to provision all resources in the Graph with every Deployment. It is up to the Driver to maintain a resource state for existing Active Resources to handle subsequent provisioning runs.

If provisioning succeeds, the Active Resource will be associated with the current Deployment.

If provisioning fails for a previously existing Active Resource, the Active Resource continues to exist, but it will remain associated to the earlier deployment where it was last provisioned successfully. This is reflected in the Usage property in the output of the humctl resources active-resource-usage CLI command:

CLI sample output

In this output, the Active Resources of type workload and postgres were provisioned “1 deploy ago”:

$ humctl resources active-resource-usage --app my-appp --env development
ResType         Class   ResID                                   Usage           Last referencing deployment     Last referencing deployment created ago
base-env        default base-env                                current deploy  18462310b7b64c99                2m35.105398032s
... OUTPUT REDACTED ...
workload        default modules.hello-world                     1 deploy ago    1846230c6106af98                2m53.73962099s
postgres        default modules.hello-world.externals.db        1 deploy ago    1846230c6106af98                2m53.739621965s

Unreferencing

If the Resource Graph being deployed does not contain a dependency to a previously existing Active Resource any more, then the Active Resource continues to exist, but it is unreferenced in the current Graph.

The unreferenced Active Resource will remain associated to the earlier Deployment where it was last provisioned successfully. This is reflected in the Usage property in the output of the humctl resources active-resource-usage CLI command as shown above.

It is therefore not sufficient to remove a resource dependency to have the resource deprovisioned. Specifically, removing a resource from the Score file and re-deploying the file it will not deprovision the resource.

This behavior is set up by design and allows rollbacks to previous Deployments without losing state in stateful resources such as Amazon S3 buckets or databases.

Deleting

You can explicitly delete an Active Resource. More specifically, you can schedule it for deletion on the next Deployment. This action requires the Administrator role in the Organization.

Deleting 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 deleting an Active Resource.

When deleting an Active Resource using one of the commands shown below, it will not be deprovisioned immediately. It continues to exist having its scheduled_deletion property set to true, and it will be deprovisioned with the next Deployment (unless that Deployment contains the same resource).

The behavior differs when not in the default Direct mode:

In GitOps mode: the behavior depends on the setup of the GitOps operator. Go here for details
In Legacy mode (DEPRECATED): the Active Resource is deprovisioned immediately

You can observe the scheduled_deletion property by querying the Active Resources of an Environment:

humctl api get /orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/envs/${HUMANITEC_ENV}/resources \
  | jq -r '.[] | [.type,.class,.res_id,.scheduled_deletion] | join(":")'

You can schedule an Active Resource for deletion regardless of whether it is associated with the current or an earlier Deployment.

From the Resource Management screen, select the Resource Definition that provisioned the Active Resource to be deprovisioned.
Select the Usage tab.
Select the Trash Can icon.
In the dialog, select Delete.

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

Variable	Example	Description
`HUMANITEC_ORG`	`my-org`	The Humanitec Organization the Application is in.
`HUMANITEC_APP`	`my-app`	The Application the Environment is in.
`HUMANITEC_ENV`	`my-env`	The Environment the Active Resource is in.
`RES_TYPE`	`postgres`	The Resource Type of the Active Resource to delete. Use the form `{resourceType}.{resourceClass}` if class is not `default`.
`RES_ID`	`shared.my-db`	The Resource ID of the Active Resource to delete.

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

Where the following environment variables are set:

Variable	Example	Description
`HUMANITEC_TOKEN`	`lsakdjhcals`	A Humanitec token of a user with an Administrator role in the Organization.
`HUMANITEC_ORG`	`my-org`	The Humanitec Organization the Application is in.
`HUMANITEC_APP`	`my-app`	The Application the Environment is in.
`HUMANITEC_ENV`	`my-env`	The Environment the Active Resource is in.
`RES_TYPE`	`postgres`	The Resource Type of the Active Resource to deprovision. Use the form `{resourceType}.{resourceClass}` if class is not `default`.
`RES_ID`	`shared.my-db`	The Resource ID of the Active Resource to deprovision.

This action cannot be performed via Terraform, as it involves fetching ephemeral objects.

Detaching

If deleting is not possible, you can add the parameter ?detach=true to the URL of the delete command to detach the Active Resource:

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

Detaching will remove the Active Resource from the Platform Orchestrator, i.e. it will not be listed any longer. The Orchestrator will not deprovision it, so any real-world resources will continue to exist.

Detaching may cause inconsistencies. Use it as an emergency fallback only. See the API documentation for more details.

The Kubernetes Custom Resource (CR) representing the Active Resource on the target cluster will continue to exist after detaching. Note that deleting the CR will cause the Humanitec Operator to deprovision the corresponding real-world object(s), if any.

Deprovisioning

Deprovisioning means removing an Active Resource from the Platform Orchestrator and removing its real-world object(s), if any.

An Active Resource is deprovisioned when one of the following conditions holds true:

The Environment the resource was provisioned in is deleted
The Active Resource has been scheduled for deletion and another Deployment into its Environment occurs which does not include the resource
The Driver of its Resource Definition changed with the latest Deployment. The Active Resource will then be deprovisioned and replaced by a new one

When using GitOps, the configuration of the GitOps operator also plays a part in the deprovisioning behavior. See the GitOps guide for details.

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 the ${context.res.guresid} 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

The GUResID is derived from the list of parameters used in the semantic alternative for a globally unique identifier shown next. It is therefore reproducible and will remain stable even when moving a Deployment to a different infrastructure, e.g. a different Kubernetes cluster.

Semantic global identifier

To obtain a human-friendly, semantic global identifier for an Active Resource (besides the non-semantic GUResID) in Resource Definitions, you can use a combination of Placeholders and prepend the Application and Environment information to the Resource descriptor elements like this:

${context.app.id}_${context.env.id}_${context.env.type}_${context.res.type}_${context.res.class}_${context.res.id}

The resulting string may have a considerable length, so make sure the target property will be able to store it.

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.

Usage	Resource ID	Examples
`workload` Resource	`modules.<workload-name>`	`modules.my-workload`
Implicit Resource	`<resource-type>`	`base-env`, `logging`
Private dependency	`modules.<workload-name>.externals.<resource-name>`	`modules.my-workload.externals.users-route`
Shared dependency	`shared.<resource-id>`	`shared.dns-common`
Resource reference or co-provisioning without `ID`	Same as Resource ID of referencing Resource	`modules.my-workload.externals.my-dns`
Resource reference or co-provisioning with `ID`	The `ID` specified in the descriptor	`shared.my-dns`, `basic`

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.

In the UI, Active Resources provisioned via Private Resource Dependencies are viewable within the workload they are private to. Active Resources from Shared Resource Dependencies are viewable at the Environment level.

From the Application overview , select the name of the Application in which you would like to view the Active Resources of
Select the Environment in the Environment Switcher in the top left of the screen.
Select the Active Deployment below the Environment switcher.

For private Resource dependencies

Select the Workload the Private Dependency is associated with.
The Active Resources currently in use by the workload are listed in the left-hand section of the screen.

For shared Resource dependencies

Select the “Shared Resources” tab in the right-hand side.
All the non-private Active Resources are listed.

humctl get active-resources

This command retrieves all the Active resources in the current environment.

More help can be found through the humctl help get command.

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

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.
`HUMANITEC_APP`	`my-app`	The Application the Environment is in.
`HUMANITEC_ENV`	`my-env`	The Environment to list Active Resources in.

This action cannot be performed by Terraform, as it involves fetching ephemeral objects.

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.

From the Resource Management screen, select the Resource Definition to view the Active Resources of.
Select the Usage tab.
All the Active Resources provisioned via that Resource Definition are listed.

There is no specific command to list Active Resources in the CLI, but the api command can be used to retrieve the same information.

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

Variable	Example	Description
`HUMANITEC_ORG`	`my-org`	The Humanitec Organization the Application is in.
`RES_DEF_ID`	`my-res-def`	The ID of the Resource Definition

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

Where the following environment variables are set:

Variable	Example	Description
`HUMANITEC_TOKEN`	`lsakdjhcals`	A Humanitec token of a user with an Administrator role in the Organization.
`HUMANITEC_ORG`	`my-org`	The Humanitec Organization the Application is in.
`RES_DEF_ID`	`my-res-def`	The ID of the Resource Definition.

This action cannot be performed vy Terraform, as it involves fetching ephemeral objects.

Active Resources

Lifecycle of a Resource #

Creating #

Subsequent deployments #

Unreferencing #

Deleting #

Detaching #

Deprovisioning #

GUResID #

Semantic global identifier #

Resource ID #

Resource IDs for workload resources #

Example #

Resource IDs for implicit Resources #

Example #

Resource IDs for private dependencies #

Example #

Resource IDs for shared dependencies #

Example #

Resource IDs for Resource references or co-provisioning #

Example #

Resource descriptor #

Listing #

By Environment #

By Resource Definition #

Lifecycle of a Resource

Creating

Subsequent deployments

Unreferencing

Deleting

Detaching

Deprovisioning

GUResID

Semantic global identifier

Resource ID

Resource IDs for workload resources

Example

Resource IDs for implicit Resources

Example

Resource IDs for private dependencies

Example

Resource IDs for shared dependencies

Example

Resource IDs for Resource references or co-provisioning

Example

Resource descriptor

Listing

By Environment

By Resource Definition