Resource Definition Versions

Every time a change to a Resource Definition is made, a new version of this Definition is being created.

There is no specific command to list Versions of a particular Resource Definition 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}/versions

Variable	Example	Description
`HUMANITEC_ORG`	`my-org`	The Humanitec Organization the Resource Definition 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}/versions" \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}"

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 Resource Definition is in.
`RES_DEF_ID`	`my-res-def`	The ID of the Resource Definition.

By default, the latest Version of a Resource Definition becomes the active Version. It means that every new Deployment will use the active Resource Definition Version to provision the Resource.

The version which has been used to provision a Resource can be found as def_version_id in the Active Resource.

The latest 50 Versions are retained for every Resource Definition along with all the Versions referenced by an Active Resource.

Pinning a Resource with a target Version

A certain Resource Definition Version can be pinned to an Active Resource. It means that a new Deployment will use the specified Version to provision this Resource. To pin a Version to a Resource, this Version must be specified as the target version for the Active Resource.

Active Resources having a pinned Resource Definition Version can be identified by having their target_def_version_id property set.

There is no specific command to pin a Version to an Active Resource in the CLI, but the api command can be used to perform the “pin” action.

humctl api post "/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/envs/${HUMANITEC_ENV}/resources/${RES_TYPE}/${RES_ID}/actions/pin" \
-d '{
"target_def_version_id": "'${TARGET_DEF_VERSION_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`	`s3`	The Resource Type of the Active Resource. Use the form `{resourceType}.{resourceClass}`, if class is not default.
`RES_ID`	`shared.my-bucket`	The Resource ID of the Active Resource.
`TARGET_DEF_VERSION_ID`	`1c8bc8cb-fec4-48f4-a266-bafac4be9ec8`	The Resource Definition Version to be pinned to the Active Resource.

curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/envs/${HUMANITEC_ENV}/resources/${RES_TYPE}/${RES_ID}/actions/pin" \
  -X POST \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -d '{
  "target_def_version_id": "'${TARGET_DEF_VERSION_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`	`s3`	The Resource Type of the Active Resource. Use the form `{resourceType}.{resourceClass}`, if class is not default.
`RES_ID`	`shared.my-bucket`	The Resource ID of the Active Resource.
`TARGET_DEF_VERSION_ID`	`1c8bc8cb-fec4-48f4-a266-bafac4be9ec8`	The Resource Definition Version to be pinned to the Active Resource.

A target Version can be unpinned from an Active Resource. Then, a new Deployment will use the Active Version again to provision the Resource. To unpin a Version set target_def_version_id property to null:

humctl api post "/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/envs/${HUMANITEC_ENV}/resources/${RES_TYPE}/${RES_ID}/actions/pin" \
-d '{
"target_def_version_id": null
}'

curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/envs/${HUMANITEC_ENV}/resources/${RES_TYPE}/${RES_ID}/actions/pin" \
  -X POST \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -d '{
  "target_def_version_id": null
  }'

Proposed Versions

When making a change to a Resource Definition, it can be specified that a new Resource Definition Version is a Proposed Version. It means that it doesn’t become an Active Version and won’t be used to provision Resources, unless it’s pinned to a certain Active Resource. It can be useful, for example, when the change needs to be applied to non-production Environments first, to be able to test it before it’s promoted to a production Environment.

A Proposed Version can be created by setting the proposed field to true when updating the Resource Definition. This will make the newly created Version a proposed one. Note that the update must contain an actual change to the Definition besides setting the proposed field.

There can be more than one proposed Version.

The proposed property is not supported by the CLI, but the api command can be used to create a Proposed Version.

humctl api patch "/orgs/${HUMANITEC_ORG}/resources/defs/${RES_DEF_ID}" \
-d '{
	"driver_inputs": {
	  "values": {
		  "region": "us-east-1"
	  },
	},
	"proposed": true
}'

Variable	Example	Description
`HUMANITEC_ORG`	`my-org`	The Humanitec Organization the Resource Definition 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}" \
  -X PATCH \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -d '{
	  "driver_inputs": {
	    "values": {
		    "region": "us-east-1"
	    },
	  },
	  "proposed": true
  }'

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

Setting the Active Version

A Resource Definition Version can be promoted to the Active Version. Promoting is possible for both proposed and not-proposed Versions, but not for archived Versions.

There is no specific command to promote a Proposed Version in the CLI, but the api command can be used to perform the promote action on the Resource Definition Version.

humctl api post "/orgs/${HUMANITEC_ORG}/resources/defs/${RES_DEF_ID}/versions/${RES_DEF_VERSION_ID}/actions/promote" \
-d '{}'

Variable	Example	Description
`HUMANITEC_ORG`	`my-org`	The Humanitec Organization the Resource Definition is in.
`RES_DEF_ID`	`my-res-def`	The ID of the Resource Definition.
`RES_DEF_VERSION_ID`	`1c8bc8cb-fec4-48f4-a266-bafac4be9ec8`	The ID of the Resource Definition Version.

curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/resources/defs/${RES_DEF_ID}/versions/${RES_DEF_VERSION_ID}/actions/promote" \
  -X POST \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}"

Variable	Example	Description
`HUMANITEC_ORG`	`my-org`	The Humanitec Organization the Resource Definition is in.
`RES_DEF_ID`	`my-res-def`	The ID of the Resource Definition.
`RES_DEF_VERSION_ID`	`1c8bc8cb-fec4-48f4-a266-bafac4be9ec8`	The ID of the Resource Definition Version.

When a proposed Resource Definition Version is promoted, it continues to be pinned to Active Resources to which it was pinned previously. Remove the pinning if you want those Active Resources to use the current Active Version going forward.

Archiving Versions

A Resource Definition Version can be archived. It’s not allowed pinning the archived Version to an Active Resource. However, Resources to which this version has been pinned before archiving continue to use this Version for provisioning.

You cannot set an archived Version to be the Active Version without unarchiving it first.

You cannot archive an Active Version.

There is no specific command to archive a Version in the CLI, but the api command can be used to perform the archive action on Resource Definition Version.

To unarchive a Version, the payload {"archived": false} can be used.

humctl api post "/orgs/${HUMANITEC_ORG}/resources/defs/${RES_DEF_ID}/versions/${RES_DEF_VERSION_ID}/actions/archive" \
-d '{"archived": true}'

Variable	Example	Description
`HUMANITEC_ORG`	`my-org`	The Humanitec Organization the Resource Definition is in.
`RES_DEF_ID`	`my-res-def`	The ID of the Resource Definition.
`RES_DEF_VERSION_ID`	`1c8bc8cb-fec4-48f4-a266-bafac4be9ec8`	The ID of the Resource Definition Version.

curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/resources/defs/${RES_DEF_ID}/versions/${RES_DEF_VERSION_ID}/actions/archive" \
  -X POST \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -d '{"archived": true}'

Variable	Example	Description
`HUMANITEC_ORG`	`my-org`	The Humanitec Organization the Resource Definition is in.
`RES_DEF_ID`	`my-res-def`	The ID of the Resource Definition.
`RES_DEF_VERSION_ID`	`1c8bc8cb-fec4-48f4-a266-bafac4be9ec8`	The ID of the Resource Definition Version.

Common use cases for using Versions

Pin a Resource to a previous Version

A Platform Engineer updates a Resource Definition, so the new Version 1c8bc8cb-fec4-48f4-a266-bafac4be9ec8 is created and becomes the Active Version.

Deployment to one of the Environments fails, as the new Resource Definition Version is not compatible with it.

The Platform Engineer pins the old (previous) Version of the Resource Definition to the Active Resource in the Environment. Re-deployment is successful.

When the Environment is ready for the Active Resource Version, the old Version can be unpinned from the Active Resource.

Pin a Resource to a proposed Version

A Platform Engineer updates a Resource Definition with the proposed flag, so the new proposed Version bf8d006e-2852-45b5-ae7a-fcee45801ea3 is created. All Resources which use this Resource Definition are still being provisioned with the old (Active) Version.

Developers who want to test the new Version on one of their Environments can pin the proposed Version to the Active Resource in this Environment (or request the Platform Engineer to do it).

After successful testing on the first Environment, Developers apply the new Definition Version to other Environments, by pinning the proposed Version to an Active Resource in the corresponding Environment.

After all Environments are successfully tested and the change is ready to go to the production Environment, the proposed Version is promoted to become the active Version.

Developers unpin the Version from all Active Resources to which it has been pinned.

Resource Definition Versions

Pinning a Resource with a target Version #

Proposed Versions #

Setting the Active Version #

Archiving Versions #

Common use cases for using Versions #

Pin a Resource to a previous Version #

Pin a Resource to a proposed Version #