Skip to content

docs: add a decision guide for choosing your environment - #1831

Merged
ennru merged 5 commits into
mainfrom
docs/sizing-availability-sovereignty
Sep 18, 2026
Merged

ennru merged 5 commits into
mainfrom
docs/sizing-availability-sovereignty

Conversation

@JustinPihony

Copy link
Copy Markdown
Contributor

Summary

  • Adds a new "Choosing your environment" page to Production Readiness, covering the three independent decisions when setting up an Akka environment: sizing (the four starting shapes — Prod/Stage/Balanced/Minimal — and their relative cost, zone count, platform replicas, and compute type), availability (zones by default vs. multi-region), and data sovereignty (region as legal jurisdiction, sub-processor boundaries).
  • These starting shapes are tuned with your Akka account team today, not a self-service setting, so the page is framed as a decision guide rather than a how-to.
  • Adds "Data sovereignty" as a named dimension in the Production Readiness overview (it wasn't previously called out), and points the overview at the new page.
  • Source content adapted from a doc supplied by @justin (akka_sizing_availability_multiregion.docx), restyled to match docs voice (second person, no marketing language, literal terminology) and re-verified against internal references for accuracy — the preset names and figures match Akka's internal cluster-tier reference exactly.

Test plan

  • docs/bin/verify-include-paths.sh passes
  • docs/bin/vale.sh — 0 errors (matches CI gate); reviewed remaining style warnings, left as-is where they match existing repo conventions (e.g. spaced em-dashes) or are false positives (e.g. flagging "AWS" as a term to lowercase)
  • Standalone asciidoctor render of both changed pages checked for syntax (Docker unavailable in the authoring environment for a full Antora build)
  • make local open to confirm nav placement and xref resolution in the full site build

…gnty

Add "Choosing your environment" to Production Readiness: how Akka
sizes a new environment (the four starting shapes and what drives
their cost), when zones are enough versus when multi-region is worth
the added cost, and how region choice determines data sovereignty.

These are account-team-mediated decisions today, not self-service
settings, so the page is written as a decision framework rather than
a how-to. Cross-linked from the production readiness overview, which
also gains "Data sovereignty" as a named readiness dimension.
@github-actions github-actions Bot added the documentation documentation related label Sep 2, 2026
@JustinPihony

Copy link
Copy Markdown
Contributor Author

Related to #1828 (per-service instance sizing): the "Sizing your environment" section here mentions per-service tuning but links to technical-overview.adoc rather than services/instance-sizing.adoc, since that page only exists in #1828 and isn't merged yet. Once #1828 merges, update that link, and reconcile the "Sizing and capacity" bullet in production-readiness/index.adoc between the two PRs' edits.


== Sizing your environment

Every environment has a fixed platform layer (orchestration, gateways, security, observability) that runs regardless of what you deploy, plus a variable service layer that scales with what you run. Platform cost does not drop as you remove services; it is the minimum cost of the environment itself. Low utilization during normal operation is expected: an environment is sized for spikes and failures, not for continuous high load.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be possible to misunderstand what environment we are talking about here. We are describing the platform infrastructure here and not the service sizing or scaling of service pods. Shouldn't service sizing and scaling be described or mentioned in same page?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, that is why I added this comment - so this one should not be completed until 1828 is done. I'll go ahead and change this PR to draft then.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#1828 merged, so I've replaced the placeholder pointer with a real link to services/instance-sizing.adoc and clarified this page covers platform-level sizing only. Marked ready for review again.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ping @patriknw

…ederation Plane

Address review feedback: "your data stays inside the region you
choose" read as contradicting the multi-region section, where data is
explicitly replicated to a second chosen region. Reword to be
plural-aware (regions you select, not a single region), and name that
this is about application data specifically, distinct from the
globally-run Federation Plane described in the technical overview.
@JustinPihony
JustinPihony marked this pull request as draft September 3, 2026 20:36
Replace the placeholder pointer to technical-overview.adoc with the
real cross-link to services/instance-sizing.adoc, and clarify that
platform-level sizing (this page) and per-service sizing (that page)
are separate, the latter being self-service. Addresses the review
comment that per-service sizing was missing from this page, which was
blocked on #1828 merging.
@JustinPihony
JustinPihony marked this pull request as ready for review September 9, 2026 04:03
@JustinPihony JustinPihony changed the title docs: add a decision guide for sizing, availability, and data sovereignty docs: add a decision guide for choosing your environment Sep 11, 2026
@ennru
ennru merged commit 4f176b3 into main Sep 18, 2026
11 checks passed
@ennru
ennru deleted the docs/sizing-availability-sovereignty branch September 18, 2026 13:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation documentation related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants