Skip to main content

​
Doc Type: Configuration Guide

Tier: Guides | Reader phase: Configuring and Operating
Back to tier overview: guides/index.md

​
What it is

A Configuration Guide is a step-by-step procedure for configuring an Aviatrix feature, workflow, or integration. It takes a reader from a defined starting state to a defined end state, in a specific tool modality. Every Configuration Guide is written for at least one tool modality. UI is the default — every guide should cover the CoPilot interface unless the feature is not exposed there. The other two modalities are additive:
  • UI — Steps performed through the Aviatrix CoPilot interface. Required for every guide where the feature is UI-accessible.
  • Terraform — Steps performed by writing and applying Terraform configuration. The goal is broad coverage, but not every guide needs a Terraform tab. Prioritize features that are commonly deployed via infrastructure-as-code.
  • API — Steps performed by calling the Aviatrix REST API directly. Include only when there is a clear audience for it — typically automation or integration scenarios where the API is the practical path. Not expected for most guides.
When multiple modalities are covered, each gets its own tab within a single guide (using <Tabs>), rather than separate documents. Create separate documents only when the procedures are significantly different in scope or prerequisites. Configuration Guides do not explain why an architecture was chosen (that’s in Architecture docs) or what an Aviatrix component does in depth (that’s in Component docs). They answer: How do I make this work? A Configuration Guide may include a brief concept overview (1–2 sentences or a short paragraph) when the feature involves a concept the reader needs to understand before following the steps. For industry-standard technologies (BGP, BFD, IPsec, etc.) that are not Aviatrix-specific, assume the reader knows the concept — a one-sentence framing is sufficient. Do not elaborate or link out; readers who need background will search for it themselves. Do not replicate what belongs in a Component doc.

​
Goal

After completing a Configuration Guide, the reader has successfully completed a specific configuration task and can verify it is working correctly. They do not need to consult any other document to finish the task — everything required is in the guide.

​
Primary personas

​
When to create a new Configuration Guide

Create a new Configuration Guide when:
  • There is a distinct, completable configuration task with a clear start and end state
  • The task requires 3 or more steps that must be performed in a specific order
  • The task is not already documented as part of a larger workflow guide
Do not create a Configuration Guide for:
  • Single-field or single-toggle configuration (that belongs in the UI Reference)
  • Conceptual explanations of what something does (that belongs in Components or Architecture docs)
  • Troubleshooting procedures (that belongs in Operational Guides)

​
Required sections

  1. Overview — 2–4 sentences at the top of the guide, before prerequisites, stating: what the reader will have achieved when they complete this guide, what the guide covers, and any important scope boundaries (“This guide covers X but not Y”). The outcome must be explicit — the reader should know exactly what state they will be in when done. This section is mandatory for all guides.
  2. Prerequisites — An H2 section listing everything that must be true before starting. Use a bulleted list. Include: required Aviatrix version, cloud provider resources that must exist, required permissions/roles, and any prior configuration tasks that must be complete. This section is not optional.
  3. Procedure — The core step-by-step content. Use one of these structures:
    • UI only: An H2 (e.g., ## Configure in CoPilot) followed by a <Steps> component
    • UI + Terraform (and optionally API): <Tabs> with one <Tab> per modality, each containing its own <Steps> component. See Style Guide for tab ordering. For the Terraform tab specifically, follow Terraform integration in UI-based guides below.
    • Each <Step> must have a title attribute and contain a complete, actionable sentence in imperative mood: “Click Save”, “Set the Gateway Size field to…”, not “You should click Save”
    • UI element names are always bold
    • Navigation paths use the > separator: CoPilot > Cloud Fabric > Gateways
    • Reuse snippets where available. When a CoPilot UI Reference page defines an action as a snippet, import and use it rather than duplicating the steps. This keeps both the guide and the UI Reference in sync from a single source. See Style Guide for snippet import syntax.
  4. Verification (required when there is a meaningful way to confirm success) — A brief section showing the reader how to confirm the configuration worked. Example: what to check in the UI, what a successful API response looks like, or what Terraform output to expect.

​
Optional sections

  • Next Steps — Links to related guides the reader should follow after completing this one (e.g., after configuring a Transit Gateway, next steps might be configuring Spoke Gateways)
  • Related Resources — Links to Component docs, Architecture docs, and Terraform/API reference for this feature. Required when the guide includes a Terraform tab; see Required Related Resources entries for the contents and ordering rules.

​
Terraform integration in UI-based guides

Most Configuration Guides start as UI procedures and grow a Terraform tab over time. To keep that integration consistent across the documentation, follow the rules below whenever a guide covers both modalities.

​
When to add a Terraform tab

Add a Terraform tab when all of the following are true:
  • The feature is supported by the Aviatrix Terraform provider or a published Aviatrix module.
  • The procedure can be expressed end-to-end in Terraform — no required step has to be performed in the UI.
  • The feature is one customers commonly deploy via infrastructure-as-code.
If Terraform support is partial or in preview, do not add a tab. Instead, add a <Note> near the top of the UI procedure pointing at the Terraform Reference page so the relationship is explicit without splitting the procedure.

​
Tab structure

Order tabs UI first, then Terraform. Use these exact title and icon attributes so every guide presents the same affordance to readers:
Always set sync={false} on the <Tabs> wrapper. Mintlify automatically syncs the selected tab across every <Tabs> group on a page that shares an identical tab title — this is intended for reader-wide preferences like a language picker, not for a guide’s modality tabs. A page with more than one <Tabs> block (for example, a guide with a separate CoPilot UI/Terraform pair per section) will otherwise force every “Terraform” tab on the page to open together when the reader clicks any one of them. sync={false} makes each <Tabs> block behave independently.

​
Section delimitation and heading hierarchy

The <Tabs> block owns its own H2 section. The H2 that introduces the tabs (for example, ## Configuration Workflow or ## Establishing Transit Gateway Peering over Public Internet) is followed only by framing prose and the <Tabs> block — no H3 siblings outside the tabs that could be mistaken for tab-equivalent peers. Close the multi-modality block with a horizontal separator (---) on its own line, surrounded by blank lines, so the visual boundary between the tabs and the next H2 is unambiguous:
The preceding and succeeding sections must both be at a higher level. They bracket the tabs block at the same outline depth, so the reader can see at a glance that the multi-modality content is one cohesive section rather than a child of the section above or below.

​
Inside the Terraform tab

Mirror the UI procedure’s shape so a reader can compare both tabs side by side without losing their place.
  1. Intro line — A single sentence naming the resources, data sources, and modules used. Link to the Aviatrix Terraform provider on first use within the guide.
  2. <Steps> block — Preferably, use the same number of phases as the UI procedure or fewer. Each <Step> contains the HCL needed for that phase as a single fenced hcl block.
  3. Data sources first, then resources or modules — Use data "aviatrix_*" blocks to look up existing infrastructure (VPCs, accounts, gateways) before referencing it. This makes dependencies explicit and improves the error message when a name is wrong.
  4. Final verification step — Every Terraform tab ends with a <Step> titled Verify and Apply the Configuration whose body is: Run terraform plan, review the planned changes, and run terraform apply.
The Terraform tab is a procedure, not a reference. Argument tables, attribute lists, and full module input/output reference belong on the Terraform Reference page for that resource or module, not inside the guide.

​
Examples sub-section

After the <Steps> block, add an ### Examples heading wrapped in an <AccordionGroup> with one or more scenario-based accordions. The intro line directly under ### Examples must call out the single most important argument or constraint shared by every example below — for example: “Every example sets enable_peering_over_private_network = false, which is the argument that forces the peering tunnels over the internet.” Each <Accordion>:
  • Title is scenario-named, not modality-named. Good: AWS Multi-Region DR Peering with Excluded CIDRs and TGW Connections. Bad: Example 1 or Terraform Example.
  • Opens with a 2–4 sentence scenario that frames who deploys this pattern, why, and what the example demonstrates that the generic walkthrough does not.
  • Uses concrete, role-aligned names for gateways, accounts, and resources — never placeholders like aws_tr_gw_name or csp1_transit. Follow the convention <role>-<cloud>-<region> (for example, transit-aws-use1, spoke-azure-app).
  • Surfaces every argument the procedure marks required. If the steps say enable_peering_over_private_network = false, every accordion sets it. A reader copying the example must end up with a working configuration that matches the procedure.
  • Comments only where intent is non-obvious. Explain why an exclusion exists, not what a CIDR is. Do not annotate every argument.
  • May end with a <Tip> pointing at the natural follow-on capability (segmentation, for_each for scale, FireNet readiness). Link to the relevant Configuration Guide rather than describing the follow-on inline.
Ship at least one Example accordion when the Terraform tab uses three or more resources, modules, or arguments whose interaction is not obvious from the steps. Single-resource procedures do not need an Examples sub-section.

​
Naming and style conventions for HCL

​
What does not belong in the Terraform tab

When a guide ships a Terraform tab, the page-level ## Related Resources section is required. It lives at the very end of the page, after every other section, and lists links in this exact order:
  1. Aviatrix Terraform provider — Link to the provider on the Terraform Registry.
  2. Aviatrix modules used by the guide — One bullet per module the Steps or Examples reference. Link to the module’s Registry page; a GitHub repository link is optional.
  3. Resources used by the guide — One bullet per aviatrix_* resource referenced in the Steps or Examples. Link to the resource’s documentation page on the Registry.
  4. Data sources used by the guide — One bullet per data "aviatrix_*" block referenced in the Steps or Examples. Link to the data source’s documentation page on the Registry.
  5. Related Aviatrix documentation — Component docs, Architecture docs, and adjacent Configuration Guides, in that order. Use relative paths for all internal links.
The list must be exhaustive for items 2–4: every module, resource, and data source the guide uses appears once. Do not omit a resource that only appears in an Examples accordion. Example skeleton:
Pin Registry links to the provider version family the guide targets. Do not link /latest/ if the guide ships for an older version whose argument set has diverged.

​
Tone & voice

Instructional and precise. Write in second person (“you”) with imperative verbs for every action step. Be specific about what to click, what to enter, and what to select. Never use vague language like “configure appropriately” or “fill in the required fields.” Every step should have exactly one action. If a step requires the reader to do two things, split it into two steps.

​
Length guidance

100–500 lines. Simple single-task guides (e.g., enabling a toggle) run 80–120 lines. Complex multi-step workflows with multiple modalities (e.g., Edge device onboarding) run 400–500 lines. If a guide exceeds 500 lines, evaluate whether it should be split into a series of shorter guides linked by a Next Steps section.

​
Frontmatter

See Frontmatter Standards for field definitions and formatting rules. Name the title in imperative form. Format: Configure [Feature] or Set Up [Feature] or Deploy [Component] for [Solution]. Example: Configure Edge Device Onboarding.

​
Mintlify components

See Style Guide for component definitions and usage rules. Use <Tabs> for multiple modalities (UI/Terraform/API) and <Steps> for high-level phase breakdown in complex multi-phase guides. Avoid <CardGroup> and <Accordion> — the procedure should be linear and fully visible.

​
Screenshots and images

  • Include a screenshot when a UI step involves a dialog, form, or page layout that is difficult to describe in text alone
  • Do not include a screenshot for every step — only where visual confirmation adds value
  • Store images in the nearest images/ folder relative to the guide file
  • Wrap all images in <Frame> with descriptive alt text
  • Alt text should describe the content, not just label it: “CoPilot Gateway configuration panel showing the Gateway Size dropdown set to C5 Large” not “Gateway settings screenshot”

​
Linking

  • Link in from: Relevant Architecture and Validated Design documents (“Related Resources” section), Operational Guides that depend on prior configuration
  • Link out to: Component docs inline when an Aviatrix component or capability is referenced and the reader may benefit from conceptual context — not to indicate this guide “deploys” that component, but to clarify what it is. A guide achieves an outcome that happens to involve components; the relationship is incidental, not hierarchical. Also link to: Terraform/API Reference for the resources involved, related Configuration Guides in a workflow series.

​
Dos and don’ts