Skip to content

CONCEPT Cited by 1 source

Pre-integration at tier creation

Definition

Pre-integration at tier creation names the architectural decision to establish shared dependencies (VPCs, IAM roles, PrivateLink endpoints, downstream- service connections) once when a tier is provisioned, rather than once per tenant at onboarding. Tenants joining the tier inherit the pre-wired connectivity automatically and cannot independently negotiate new dependencies.

Canonical wiki instance: AWS Architecture Blog's 2026-05-12 ad-serving platform (Source: sources/2026-05-12-aws-building-hybrid-multi-tenant-architecture-for-stateful-services). Verbatim:

"The key design principle is that we pre-wire downstream service dependencies at tier creation, not at tenant onboarding. AWS PrivateLink connections from the tier VPC to each downstream service VPC are established after the tier is provisioned. After onboarding tenants to that tier, they automatically inherit full downstream connectivity. This single architectural decision is the primary reason for the 80 percent reduction in infrastructure setup steps."

What the decision structurally changes

Before pre-integration, every new tenant's onboarding workflow includes these steps:

  1. Create tenant's AWS account (or VPC / IAM role / etc.).
  2. Establish networking (VPC peering, Transit Gateway, or PrivateLink from the tenant's account to each downstream service's account).
  3. Create IAM roles that grant the tenant's workload access to downstream services.
  4. Set up observability endpoints, log aggregation, monitoring.
  5. Integration-test each downstream dependency from the tenant's environment.
  6. Onboard the tenant's application (the actual product work).

Steps 2–5 are infrastructure provisioning that has nothing to do with the tenant's product-specific configuration. Running them per-tenant means running them 18 or 180 or 1,800 times, each with its own failure modes, approvals, and network-engineering involvement.

Pre-integration collapses steps 2–5 into a single one-time investment at tier creation:

  1. Create tier infrastructure (VPC, ALB, PrivateLink endpoints, IAM roles, monitoring).
  2. Establish downstream-service connectivity for the whole tier.
  3. Integration-test each downstream dependency from the tier once.
  4. Set up observability with tenant-dimensioned metrics and logs (no per-tenant observability setup).

Now onboarding a tenant reduces to:

  1. Add a listener rule to the existing ALB.
  2. Create a dedicated ECS cluster in the existing VPC.
  3. Register the ECS service to the existing target group.
  4. Deploy the tenant's product-specific configuration.

Steps that were per-tenant (2–5 above) are now per-tier.

The 52d → 7d breakdown

The canonical source discloses a verbatim breakdown of the before-state 52-day onboarding:

  • ~2 weeks: AWS account provisioning
  • ~3 weeks: VPC and networking setup
  • ~1 week: IAM role configuration
  • ~2 weeks: downstream service integration and testing

All four blocks are dependency setup, not product work. Pre-integration eliminates them as per-tenant costs. The remaining 7 days is "primarily testing and validation, because infrastructure is pre-provisioned."

Why the decision is structural, not operational

The onboarding speedup is often attributed to automation ("automate provisioning scripts" → faster onboarding). The canonical post is explicit that automation is not the source of the 80% setup-step reduction:

"Infrastructure setup steps per tenant: 80 percent fewer"

This is a structural change in what gets provisioned, not a speed-up of existing steps. Automation reduces the cost of each step; pre-integration eliminates most steps entirely. The two are complementary, but pre-integration is primary.

Cost payoff analysis

Pre-integration requires up-front investment in tier design:

  • Engineers spend time designing the tier's shared dependencies to work for all possible tenants, not just the current one.
  • The tier must absorb downstream changes (new services, new endpoints, migrations) without regressing existing tenants.
  • Tier changes touch many tenants at once; blast-radius engineering becomes more important.

This up-front cost is paid once per tier. The benefit scales with tenant count: at 10 tenants per tier, the pre-integration cost is amortised 10-fold; at 100 tenants per tier, 100-fold.

The canonical architecture's capacity ceiling is 50 tenants per infra group, with multiple infra groups per cell; amortisation improves with tier density.

What pre-integration requires of downstream services

For the pattern to work, downstream services must be:

  • Multi-tenant aware at the data layer — the downstream-service owner must be able to serve all tenants of the tier through a single endpoint (no per-tenant endpoint-per-tenant-service).
  • Stable over tenant-onboarding timescales — a downstream service that changes API contract monthly forces per-tenant re-integration work despite the pre-wiring.
  • Tolerant of shared connectivity — PrivateLink endpoints from the tier VPC are shared by all tenants; the downstream service must accept traffic from this shared source.

In AWS terms: downstream services expose a VPC Endpoint Service once; the tier establishes an interface endpoint to it once; all tenants in the tier consume the endpoint through shared IAM roles.

What pre-integration forfeits

  • Per-tenant dependency choice. A tenant that needs a different downstream service version or a different endpoint configuration cannot get it without either breaking the tier's shared-dependency invariant or being promoted to its own tier.
  • Per-tenant audit trails on dependency setup. The provisioning event happens once at tier creation, not attributable to any individual tenant.
  • Per-tenant cost attribution for shared infrastructure. PrivateLink endpoint cost (~$7.30/month) is amortised across tenants; per-tenant billing requires tag-based attribution rather than native per-resource billing.

These forfeits are deliberate — the architecture trades per-tenant flexibility for onboarding speed.

Tier-promotion pathway

Tenants whose requirements diverge from the tier's shared dependencies are promoted to a different tier rather than customised in place. The canonical architecture has High TPS, Standard TPS, Low TPS tiers; tenants move between tiers as their traffic profile evolves, absorbing the tier's shared dependencies at each promotion. See patterns/tier-cell-infra-group-hierarchy for the tiering mechanism.

Relationship to neighbouring concepts

Anti-patterns

  • Pre-integrating at tenant creation, not tier creation — defeats the amortisation. Still runs dependency setup per-tenant.
  • Pre-wiring one downstream service per tier but negotiating the rest per-tenant — the slowest step determines the total onboarding time. Pre-integration only pays off if all shared dependencies are covered.
  • Pre-integrating at account level but still requiring per-tenant network setup inside the account — the onboarding bottleneck moves from account provisioning to VPC provisioning but the total time stays high.
  • Treating pre-integration as one-time — downstream services evolve; the tier needs continuous integration with downstream changes, not a one-shot setup.

Seen in

  • sources/2026-05-12-aws-building-hybrid-multi-tenant-architecture-for-stateful-services — canonical wiki home. The AWS post explicitly names pre-integration at tier creation as "the primary reason for the 80 percent reduction in infrastructure setup steps" — a rare case where a post attributes a measured metric to a specific architectural decision. The 52d → 7d onboarding improvement and 80% setup-step reduction both derive from this one lever.
Last updated · 542 distilled / 1,571 read