Repository navigation
[Feature]: cloud architectures need a containment grammar (an Azure case study) #63
Description
Activity
This identifies a real correctness gap, especially where flattening administrative and network scopes can misstate security. Direction accepted as a provider-neutral Architecture containment variant, not
type-architecture-azure.md: combine Architecture connectors with Nested containment, distinguish administrative scopes from traffic boundaries, and use generic metadata such asdata-scope-kind/data-parent. Azure can be the worked case study, including managed services outside subnets with private endpoints inside. Please rebase after #66 because it touches the same reference.Thanks for the direction, and for framing it as a correctness problem rather than a
styling one. Provider-neutral containment insidetype-architecture.mdis the better
call, and it makes the Azure work a case study instead of a special case.Confirming what I understood, so we build the same thing:
- Containment comes from Nested, connectors from Architecture.
- Administrative scopes (subscription, resource group) and traffic boundaries
(virtual network, subnet) get different shapes, because a billing-and-permissions
container and a boundary traffic cannot cross without an explicit rule are not the
same object. Bands for the first, boxes for the second. - Metadata stays generic:
data-scope-kind/data-parent, no provider prefix. - Managed services sit outside every subnet, with their private endpoints inside.
On that last point, one detail worth writing into the reference: it is the single most
common error in cloud architecture diagrams, and it is not cosmetic. Drawing a managed
database inside a subnet tells the reader it sits behind that subnet's security rules,
which it does not.I have a worked example ready, derived from a production deployment with every
identifying value replaced. It exercises exactly the cases above: two administrative
scopes, two networks joined by a peering, and four managed services reached through
private endpoints that live in a subnet while the services do not.
Proposed scope for the PR:
- The containment section in
type-architecture.md, provider-neutral, with the
scope-kind vocabulary and the geometry. - Azure as the worked example, in the three required variants.
For AWS and GCP the shape is the same (account or project, then VPC, then subnet), so
whoever knows those platforms best can contribute their examples on top of the same
grammar without touching the reference again. Happy to leave clear extension points for
that rather than guess at conventions I do not use daily.I will rebase on #66 as you asked. Is it close enough that I should wait, or would you
rather see a draft against the current reference so the shape can be discussed while #66
lands?Your four-bullet summary matches what I accepted exactly — bands for administrative scopes, boxes for traffic boundaries, generic
data-scope-kind/data-parent, and managed services outside every subnet with only their private endpoints inside. Please do write the PaaS-placement rule into the reference itself; you're right that it's the most common correctness error in the wild and it deserves to be normative, not an example detail.On sequencing: don't wait for #66. It's still in revision, so open your draft against the current
type-architecture.mdnow and mark it as expecting a rebase — the shape discussion (containment geometry, scope-kind vocabulary, the axis-by-width rule) is worth having in parallel, and the eventual rebase is mechanical since #66 converts colors to role placeholders rather than touching zone geometry.The worked example looks like the right stress case: two administrative scopes, a peering, and private endpoints for services that live outside the subnets. Leaving AWS/GCP as extension points on the same grammar is the right call too. Looking forward to the draft.
What are you trying to show?
I want to show an Azure architecture where the network hierarchy itself carries
the meaning, and the reader needs to know what sits inside which subnet.
type-architecture.mdis provider-agnostic, which is the right default. But itcaps at three zones, flat, with no nesting, and its examples label them
EDGE,CORE SERVICES,DATA. A real Azure topology has four levels of containmentthat are not interchangeable:
Drawing this today means flattening two levels into one label. I ended up with a
zone eyebrow reading
VNET · SNET-APP, which passes every gate and still liesabout the hierarchy.
The distinction is load-bearing, not cosmetic. A resource group holds no
traffic — it groups resources for billing, permissions and lifecycle. A virtual
network is a boundary traffic does not cross without an explicit rule. A reader
who cannot tell those apart cannot tell whether a design is secure.
There is a second thing the current type cannot express, and it is the error I
see most often in Azure diagrams in the wild: a PaaS service is never inside a
subnet. Azure SQL, Key Vault and Storage belong to the resource group; what
lives in the subnet is their private endpoint. Diagrams that put the database
inside the subnet tell the reader it sits behind that subnet's NSG, which is
false.
Proposed solution
I have a working implementation and I would rather ask before polishing it for a
PR, because the shape of the answer changes the work.
The open question is the same one as #55: is this a new type, or a variant of
an existing one? I can see it either way:
type-architecture-azure.md, extendingtype-architecture.md. Allof that type's rules still apply; the new file adds only the containment
grammar. That is what I built.
type-architecture.mdgains, usable by anycloud. AWS has the same shape (account → VPC → subnet) and, as far as I can
tell, is equally unserved today — the repo's own showcase example draws an AWS
architecture with the generic grammar.
What the implementation does, in case it is useful either way:
comes from
type-nested.md: consistent insets, eyebrow per level, fillsstepping up inward, strokes hardening. Administrative levels render as
horizontal bands, which
type-swimlane.mdandtype-layers.mdalreadyestablish.
sibling VNets and sibling subnets run on perpendicular axes, and the choice of
axis is decided by width, not taste. Azure's own reference architectures put
four subnets in a row; that only works because each holds a single resource.
them in architecture diagrams but require they appear as they do in Azure, so
they are multi-colour and
lint-skin.pyrejects them once per gradient stop.Keeping the shipped examples monochrome is the only way both constraints hold,
and the containment grammar is what makes a diagram read as Azure anyway — the
hierarchy, not the logo.
data-azure-*attributes, soa checker can assert real geometric containment, PaaS placement, private
endpoint targets and peering endpoints. Both
lint-skin.pyandself_check.pyaccept those attributes unchanged.I validated it against Microsoft's published reference architectures rather than
cases I invented. The AKS baseline reproduces cleanly at the network layer. What
it cannot express is the inside of the cluster — node pools and pods nest four
levels deeper and are Kubernetes objects, not Azure resources. I think that is a
separate type and I am not proposing it here.
Scope
New diagram type (reference + 3 examples + gallery)
Design-system fit
Happy to open the PR with the reference, the three variants, the gallery entry
and the frontmatter hook once you tell me which shape you prefer. If the answer
is that provider-specific grammars do not belong in the skill, that is a useful
answer too and I will keep it as a local extension.