Designing Directory Hierarchies for Multi-Environment BTP Landscapes

Explanation

As an SAP BTP landscape grows beyond a handful of subaccounts, flat organization becomes unmanageable. A global account can contain directories, which are optional grouping containers sitting between the global account and subaccounts. Directories let you cluster subaccounts logically - for example by environment (DEV, QA, PROD), by line of business (Sales Cloud Integration, Finance Integration), or by region (EU, US, APJ) - and then apply policies once at the directory level instead of repeating them on every subaccount. Why this matters in real projects: a mid-size enterprise typically ends up with dozens of subaccounts once Integration Suite, SAP Build, event mesh, and various custom Cloud Foundry or Kyma workloads are all provisioned separately per environment and per team. Without directories, entitlement quotas, authorization assignments, and cost tracking must be managed subaccount-by-subaccount, which is error-prone and slow to audit. Directories solve this by allowing three key capabilities: directory-level entitlement quotas (a pool of service plan quota that member subaccounts draw from), directory features such as enabling standardized role collections or custom IDPs across all children, and directory-level authorization management so that a set of administrators is scoped to only the subaccounts inside that directory rather than the whole global account. Design considerations: the two most common hierarchy patterns are environment-first (Directory: Production > subaccounts: SAP-CPI-PROD, Integration-Advisor-PROD) and business-unit-first (Directory: Finance > subaccounts: Finance-DEV, Finance-QA, Finance-PROD). Environment-first hierarchies work well when the same governance team owns all production workloads regardless of business domain, and is generally preferred in regulated environments because it lets you apply a single stricter security policy to all PROD directories. Business-unit-first hierarchies work well when different application teams own their own subaccounts end-to-end and need visibility scoped to their own domain across environments. A hybrid is also common: top-level directories per business unit, with a nested pattern (sub-groupings via naming convention, since deep nesting has practical limits) reflecting environment inside each. Entitlement quota inheritance is a critical implementation detail: when you assign a quota (for example, a certain number of Integration Flows or a specific CPU/memory allocation for Cloud Foundry) to a directory, that quota becomes a shared pool that any subaccount under that directory can consume, up to the directory total, as long as the global account itself has sufficient quota assigned to the directory. This is different from assigning quota directly to each subaccount, which creates isolated pools that cannot be reallocated without going back to the entitlements screen. Directory-level pooling is generally recommended for elastic workloads (e.g., non-production sandboxes where usage fluctuates) while direct subaccount-level entitlement is often preferred for production systems where you want a hard, auditable ceiling that cannot silently be consumed by a sibling subaccount's spike in usage. From a runtime perspective, directories do not host runtime workloads themselves - all actual Cloud Foundry orgs/spaces, Kyma clusters, and service instances always live inside subaccounts. Directories are purely an administrative and entitlement grouping construct. This means a directory reorganization (moving a subaccount from one directory to another) does not affect running applications, integration flows, or connectivity, but it does immediately change which quota pool and which set of directory administrators govern that subaccount going forward. One frequently underestimated aspect is the interaction between directory features and subaccount-level overrides: certain directory features, once enabled, become mandatory for all subaccounts underneath and cannot be individually disabled at the subaccount level. This is powerful for enforcing standards (for example, mandating a corporate identity provider trust configuration across every subaccount in a directory) but it also means that testing a new capability broadly before full rollout requires either a dedicated sandbox directory or careful sequencing, since you cannot easily exempt one subaccount from a directory-enforced feature.

Code example

# Example: btp CLI commands illustrating directory-based organization# (illustrative syntax - always verify current command names/flags against your CLI version) # 1. Create a directory for production workloadsbtp create accounts/directory --display-name "PRODUCTION" \  --description "All production subaccounts - EU region" \  --subdomain prod-directory # 2. Enable directory-level entitlements management featurebtp enable accounts/directory-feature --directory-id <dir-guid> \  --feature ENTITLEMENTS # 3. Assign a pooled entitlement quota to the directorybtp assign accounts/entitlement --to-directory <dir-guid> \  --for-service integration-suite \  --plan standard \  --amount 5 # 4. Move an existing subaccount under the new directorybtp move accounts/subaccount --id <subaccount-guid> \  --to-directory <dir-guid> # 5. List subaccounts under a directory to verify groupingbtp list accounts/subaccount --directory <dir-guid> # Naming convention example used across a project:# <businessUnit>-<system>-<env>  e.g. FIN-CPI-PROD, SALES-EVENTMESH-QA

Real project scenario

A retail company running SAP Integration Suite for order-to-cash integrations started with five subaccounts created ad hoc by different project teams, each with its own entitlement allocation. Six months in, the platform team could not answer a basic audit question - how much total Integration Flow capacity was allocated to production versus non-production - without manually opening each subaccount's entitlement screen. They restructured the global account into three top-level directories (PRODUCTION, NON-PRODUCTION, SANDBOX), moved existing subaccounts into the appropriate directory without any downtime to running integration flows, assigned pooled quotas at the directory level for non-production and sandbox (allowing developers to flexibly provision trial integration suite tenants for short-lived proof-of-concepts), and kept hard per-subaccount quotas for production. This gave the platform team a single screen to review production capacity and let developers self-serve sandbox capacity within the pooled non-production quota without repeated entitlement change requests.

Common mistakes

• Creating deep, many-level directory nesting that mirrors an org chart, making navigation and automation scripts unnecessarily complex • Assigning production and non-production subaccounts to the same directory, causing shared pooled quota where a non-production spike can starve production capacity • Enabling a directory feature broadly before validating its impact on one representative subaccount, resulting in unexpected mandatory behavior across many systems at once • Forgetting that moving a subaccount to a new directory changes its administrator scope, which can accidentally lock out or grant excess access to existing admins • Relying purely on naming conventions instead of actual directory structure for governance, so automated policy enforcement tools cannot reliably target the intended group of subaccounts

Best practices

• Design the directory hierarchy before creating subaccounts, based on how administration, quota, and policy responsibilities are actually split across teams • Keep production subaccounts in dedicated directories with hard, non-pooled entitlement quotas to avoid cross-tenant quota contention • Use pooled directory-level quotas for elastic, non-production workloads such as sandboxes and short-lived proof-of-concept environments • Pilot any directory-level feature enablement on a single low-risk subaccount before rolling it out broadly, since some features cannot be selectively disabled per subaccount • Document the chosen hierarchy pattern (environment-first, business-unit-first, or hybrid) and the rationale, so future reorganizations are deliberate rather than accidental • Re-validate administrator role collection assignments immediately after moving any subaccount between directories

Interview angle

Interviewers often probe whether a candidate understands that directories are an administrative/entitlement grouping layer with no runtime footprint of their own, and can articulate the trade-off between pooled directory-level quotas (flexible, shared risk) versus subaccount-level quotas (isolated, harder ceiling). A strong answer also distinguishes environment-first versus business-unit-first hierarchy patterns and explains why regulated production landscapes often favor environment-first grouping for uniform security policy enforcement.