Shared Resources

Learn how to use Shared Resources in Humanitec
Shared Resources are available to all Workloads in an Application. This can be particularly useful when migrating an application from a monolithic architecture to a microservice architecture - wherein multiple Workloads need to access the same database. Or when different Workloads need to respond to requests for a shared domain name.

Adding a Shared Resource

Screenshot of the UI - App Details Screen. The "Shared resources" tab is shown
1. Go to App Details page for the App that needs the Shared Resource.
2. Select the Shared resources tab at the top of the draft deployment.
3. Select the type of Shared Resource that you require from the Add shared resource dropdown.
This will open a dialog box asking you to provide a Resource ID.
4. Give the Resource an ID.
5. Click Done.
IDs must begin and end with lowercase alphanumeric ([a-z0-9]) characters, but may also contain dashes (e.g my-db). They must also be unique within the App.
To add a shared Resource to an existing App via the API, you'll need to create a new Delta.
1. To do this you'll be making a POST request to the{orgId}/apps/{appId}/deltas endpoint with a JSON object that creates the dependency for the shared Resource you wish to add.
export HUMANITEC_ORG="my-org"
export HUMANITEC_APP="my-app"
export HUMANITEC_ENV="my-environment"
export HUMANITEC_TOKEN="my-token"
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ${HUMANITEC_TOKEN}'
-d @- <<'EOF'
"metadata": {},
"modules": {},
"shared": [
"op": "add",
"path": "/my-shared-db",
"value": {
"type": "postgres"
EOF | jq '.id'`
In the example above we're adding a new resource object called "my-shared-db" to the shared resources set. The "op" field is specifying the operation (i.e. "add"), the "path" field is saying where this new object is relative to the "shared" resources (i.e. "/my-shared-db"), and the "value" is supplying the resource type.
You can read more about this endpoint in our API docs.
2. Next you'll need to Deploy this change with a POST request to the{orgId}/apps/{appId}/envs/{envId}/deploys endpoint.
-H 'Content-Type: application/json'
-H 'Authorization: Bearer ${HUMANITEC_TOKEN}'
-d @- <<'EOF'
"comment": "API example",
"delta_id": "$HUMANITEC_DELTA"
Our CLI is currently in closed beta. Please contact us if you want to learn more.
This Resource is now ready to use in your Workloads.
Similar to private Resources that are specified at the Workload level (Read more about this in work with workloads), shared Resources provide template Placeholders. Shared Resources use the Placeholder path prefix shared, whereas resources defined at the Workload level use the Placeholder prefix externals.
Read more about Placeholders here.

Role-Based-Access-Control (RBAC)

Creating or deleting Shared Resources requires Developer level access (or above) to the App you wish to edit. To learn more about RBAC in Humanitec read the guide here.