Doc Type: Validated Design
Tier: Concepts & Architectures | Reader phase: Understanding
Back to tier overview: concepts-architectures/index.md
What it is
A Validated Design documents the conceptual outcome of a specific, implemented deployment of Aviatrix aligned to a business outcome or workload scenario. Where an Architecture document describes a generic, reusable pattern, a Validated Design says: “This is how we solved this specific problem — here is the design that was built and what it achieves.” Validated Designs typically align with a Solution or a defined business outcome, and their titles reflect that: Egress Security for EKS Workloads, not Hub-and-Spoke with DCF. Validated Designs cover any type of implemented outcome. The subject is the scenario and its result, not any particular category of infrastructure or policy. Validated Designs remain at the conceptual level. They do not contain IP addressing, sizing parameters, environment-specific configuration values, or procedural steps — those belong in Configuration Guides. They document the what of the implemented outcome: the logical design, the components and workloads involved, the decisions made, and the result achieved. A Validated Design is effectively a superset of an Architecture — it incorporates the relevant architecture patterns and component knowledge, applies them to a specific scenario, adds the workloads and systems involved, and documents the outcome. They show the full picture including workloads, cloud constructs, and external systems, not just the Aviatrix layer. A reader consulting a Validated Design should come away understanding what was built and why, not how to build it step by step.Goal
After reading a Validated Design, the reader understands how a specific solution scenario was implemented at the conceptual level — what was built, which architecture patterns were applied, what design decisions were made, and what the outcome achieves. They can use this as a reference point when designing their own implementation and navigate to the relevant Architecture docs and Configuration Guides for depth.Primary personas
When to create a new Validated Design
Create a Validated Design when:- A specific solution scenario has been implemented using Aviatrix — by a customer, a solutions engineer, or an internal team
- The implementation is concrete enough to document as a logical design (not a hypothetical or planned deployment)
- A solutions engineer or architect can describe the outcome at the conceptual level without exposing environment-specific details
Required sections
- Design Summary — 4–6 sentences: what scenario this design addresses, what was implemented, and what the outcome achieves. Written at a conceptual level — no environment-specific details.
- Logical Design — A conceptual diagram of the implemented design. Validated Designs are typically more elaborate than Architecture diagrams — they include not just the Aviatrix components but also the workloads, cloud constructs, and external systems the design connects or protects. Show how everything relates and what flows or boundaries the design establishes. Label all elements by type and role. Do not include IP addresses, instance sizes, region names, or quantity counts — this is a logical diagram, not an environment map.
- Architecture Patterns Applied — Which Architecture documents this design draws on, and how. One sentence per pattern explaining how it was applied in this specific scenario. Link to each Architecture document.
- Design Decisions — The key choices made for this specific scenario: which components were selected, which architectural variants were chosen, and why. Each decision should state the option chosen and the reasoning, without prescribing implementation parameters.
- Outcomes — What the design achieves: the security posture it establishes, the connectivity model it enables, the operational properties it provides. Written qualitatively — not as performance measurements or test results.
- Known Constraints and Limitations — What this design does not handle and what conditions would require a different approach.
- Related Resources — Links to: the Architecture documents this design draws on, Configuration Guides for implementing this design, and related Validated Designs.
Optional sections
- Security Posture — When the design has specific security properties worth calling out beyond what is covered in Outcomes: policy model, segmentation boundaries, or compliance alignment
- Operational Characteristics — High-level notes on day-2 behavior: how the design handles failure, what changes in an upgrade, what monitoring it requires — at a conceptual level only
- Customer Context — If a customer story can be shared (anonymized or with permission), a brief description of the scenario that drove this design reinforces the “validated” claim
Tone & voice
Conceptual and authoritative. The reader is evaluating whether this design matches their scenario. Write with precision about the design itself — what it is, what it does, why decisions were made — without prescribing environment-specific parameters. Avoid instructional language (“configure,” “click,” “set”). Describe the outcome as a fact: “The design establishes east-west policy enforcement at the transit layer,” not “You will configure east-west policy enforcement.”Length guidance
200–350 lines for the document itself. Performance tables and topology diagrams add apparent length — keep prose tight.Frontmatter
See Frontmatter Standards for field definitions and formatting rules. Name the title after the business outcome or workload scenario the design addresses — not the architecture pattern it uses. Titles should read like a solution outcome, not a technical label. Examples: Egress Security for EKS Workloads, Securing Pipeline Workloads, MCP Egress Control. Do not use “Validated Design” in the title itself — that label belongs in the page type or navigation context, not the title.Mintlify components
See Style Guide for component definitions and usage rules. Use<Warning> for constraints that could cause production failures if ignored, <Note> for key design decisions or context-dependent behavior, and <Tabs> for comparing variants of the same scenario. Do not use <Steps> — this is not a procedural document.
Linking
- Link in from: Solution documents that reference this design (optional), Architecture documents that this design applies, Validated Designs index page
- Link out to: Architecture documents this design draws on, Component documents for the capabilities involved, Configuration Guides that implement the design