> ## Documentation Index > Fetch the complete documentation index at: https://docs.aviatrix.com/llms.txt > Use this file to discover all available pages before exploring further. # Configuration guide # Doc Type: Configuration Guide > **Tier**: Guides | **Reader phase**: Configuring and Operating\ > **Back to tier overview**: [guides/index.md](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 ``), 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 | Persona | How they use it | | - | - | | **Engineer** | Primary audience. Follows the guide to configure and deploy | | **Operator** | Uses UI guides for day-to-day configuration tasks | | **Developer** | Primarily uses API and Terraform sub-types | *** ## 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 `` component * **UI + Terraform (and optionally API)**: `` with one `` per modality, each containing its own `` component. See [Style Guide](../style-guide.md#tabs-and-tab) for tab ordering. For the Terraform tab specifically, follow [Terraform integration in UI-based guides](#terraform-integration-in-ui-based-guides) below. * Each `` 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](../style-guide.md) 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](#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 `` near the top of the UI procedure pointing at the [Terraform Reference](../reference/terraform-reference.md) 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: ```mdx theme={null} ... ... ``` **Always set `sync={false}` on the `` wrapper.** Mintlify automatically syncs the selected tab across every `` 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 `` 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 `` block behave independently. ### Section delimitation and heading hierarchy The `` 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 `` 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: ```mdx theme={null} ## Configuration Workflow ... ... --- ## View the Network Topology ``` 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](https://registry.terraform.io/providers/AviatrixSystems/aviatrix/latest) on first use within the guide. 2. **`` block** — Preferably, use the same number of phases as the UI procedure or fewer. Each `` 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 `` 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](../reference/terraform-reference.md) page for that resource or module, not inside the guide. ### Examples sub-section After the `` block, add an `### Examples` heading wrapped in an `` 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 ``: * **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 `--` (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 ``** 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 | Aspect | Rule | | - | - | | Identifier style | `snake_case` for Terraform resource, module, and data source labels (`module "transit_aws"`, `data "aviatrix_transit_gateway" "transit_aws"`) | | Cloud-side resource names | `kebab-case` (`gw_name = "transit-aws-use1"`) | | Module versions | Pin to the product version of the guide. An 8.2 guide pins `version = "8.2.0"`; a 9.0 guide pins `version = "9.0.0"` | | Default-valued arguments | Set explicitly when the prose claims the behavior (for example, `ha_gw = true`). The example then matches what the prose says | | Argument alignment | One space after the longest key in each block. Do not mix two alignment styles in the same example | | `` usage | Only when a single step has two equally valid HCL forms (for example, raw provider resources vs. an Aviatrix module). Do not use `` to separate provider-version variants — pin one version per guide | ### What does not belong in the Terraform tab | Content | Where it belongs | | - | - | | Full argument reference for a resource or module | [Terraform Reference](../reference/terraform-reference.md), or the Terraform Registry page it links to | | Provider authentication and version compatibility | Provider Reference (see [Terraform Reference](../reference/terraform-reference.md)) | | Architecture trade-offs being illustrated by the example | Architecture or Solution doc (Concepts & Architectures tier) | | Long lists of advanced tuning arguments | A standalone Configuration Guide for the advanced workflow, or a `` linking to the Terraform Reference | ### Required Related Resources entries 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: ```mdx theme={null} ## Related Resources - [Aviatrix Terraform provider](https://registry.terraform.io/providers/AviatrixSystems/aviatrix/latest/docs) - [terraform-aviatrix-mc-transit module](https://registry.terraform.io/modules/terraform-aviatrix-modules/mc-transit/aviatrix/latest) - [terraform-aviatrix-mc-spoke module](https://registry.terraform.io/modules/terraform-aviatrix-modules/mc-spoke/aviatrix/latest) - [aviatrix_transit_gateway_peering resource](https://registry.terraform.io/providers/AviatrixSystems/aviatrix/latest/docs/resources/aviatrix_transit_gateway_peering) - [aviatrix_transit_gateway data source](https://registry.terraform.io/providers/AviatrixSystems/aviatrix/latest/docs/data-sources/aviatrix_transit_gateway) - [Transit Gateway Peering Workflow](/docs/enterprise/8.2/guides/connectivity/peering/transit-gateway-peering-workflow) - [Aviatrix Transit Gateway component](/docs/enterprise/8.2/concepts-architectures/components/networking/transit-gateway) ``` 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](../frontmatter.md) 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*. ```yaml theme={null} --- title: "Configure [Feature Name]" description: "Step-by-step instructions for configuring [feature] in [product] — covering prerequisites, [UI/Terraform/API] procedure, and verification." --- ``` *** ## Mintlify components See [Style Guide](../style-guide.md) for component definitions and usage rules. Use `` for multiple modalities (UI/Terraform/API) and `` for high-level phase breakdown in complex multi-phase guides. Avoid `` and `` — 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 `` 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 | Do | Don't | | - | - | | Start every action step with an imperative verb | Write steps as observations ("The page shows...") | | Bold every UI element name exactly as it appears in the product | Paraphrase UI labels or use quotation marks instead of bold | | Use `>` for navigation paths | Use arrows, slashes, or "go to" for navigation paths | | Include a Prerequisites section — always | Assume the reader has everything they need | | Split multi-modality procedures into tabs | Create separate documents for UI vs. Terraform vs. API | | State what a successful outcome looks like | Leave the reader unsure whether it worked | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.