Skip to main content

​
Doc Type: Operational Guide

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

​
What it is

An Operational Guide covers procedures performed after initial configuration — the recurring, event-driven, or exceptional tasks involved in keeping Aviatrix running in production. Where Configuration Guides answer “how do I set this up?”, Operational Guides answer “how do I keep this running, fix it when it breaks, or move it forward to a new version?” There are two sub-types:
  • Upgrade Guides — Procedures for upgrading the Aviatrix platform (controller, gateways, CoPilot) to a new version. These are high-stakes, sequential, and often irreversible — tone and structure reflect that.
  • Troubleshooting Guides — Procedures for diagnosing and resolving problems in a running Aviatrix environment. These follow a symptom → diagnosis → resolution structure.
A third sub-type exists but is less common:
  • Maintenance Guides — Procedures for routine operational tasks: backup and restore, certificate rotation, license management, platform patching.

​
Goal

After completing an Operational Guide, the reader has performed a specific operational task — upgrade, diagnosis, or maintenance — safely and without service disruption. For troubleshooting guides specifically: the reader has either resolved their issue or arrived at a clear next step (such as a support escalation with the right diagnostic data in hand).

​
Primary personas

​
When to create a new Operational Guide

Create a new Operational Guide when:
  • There is a distinct operational task with real consequences for doing it incorrectly
  • The task is event-driven (triggered by a failure, a scheduled upgrade window, an alert) rather than part of initial setup
  • The task requires domain knowledge about how the system behaves under operational conditions
Do not create an Operational Guide for:
  • Initial configuration tasks — those belong in Configuration Guides
  • Conceptual explanations of how the system works — those belong in Architecture or Component docs
  • Field-level reference for UI panels — that belongs in UI Reference docs

​
Required sections — Upgrade Guides

  1. Before You Begin — An H2 section covering: required pre-upgrade steps (backups, health checks), compatibility requirements (supported upgrade paths, version constraints), estimated downtime or service impact, and rollback options. This section is mandatory and must be read before the reader touches anything.
  2. Upgrade Procedure — Step-by-step numbered instructions. Each step must be atomic and verifiable. Where the system performs automated steps, describe what the reader should observe and how long to expect it to take.
  3. Verification — What to check after the upgrade to confirm success: version numbers, gateway connectivity, health dashboards.
  4. Rollback Procedure — What to do if the upgrade fails or produces an unacceptable result. If automatic rollback is available, describe it. If manual rollback is required, provide the steps.
  5. Troubleshooting — A section (or link to a dedicated troubleshooting guide) covering common upgrade failure modes with their symptoms and resolutions.

​
Required sections — Troubleshooting Guides

  1. Overview — 2–4 sentences describing what problems this guide covers, what tools or access the reader needs, and any automatic recovery behavior to be aware of (e.g., “The system automatically rolls back if…”).
  2. Problem sections — One H2 per distinct problem category. Each H2 contains:
    • Symptoms — What the reader observes (error messages, UI states, log entries). Use exact error text where possible, formatted as inline code.
    • Diagnosis — Steps to confirm the problem and rule out alternatives.
    • Resolution — Numbered steps to fix the problem. If multiple resolutions exist, use sub-headings.
  3. Escalation — When and how to engage Aviatrix Support, including what diagnostic information to collect before opening a ticket.

​
Required sections — Maintenance Guides

  1. Prerequisites — What must be true before starting (same pattern as Configuration Guides).
  2. Procedure — Numbered steps for the maintenance task.
  3. Verification — How to confirm the task completed successfully.
  4. Schedule and Frequency (if applicable) — Recommended frequency, and whether the task can be automated.

​
Optional sections

  • Impact Assessment — For upgrade and maintenance guides, a table of what is and isn’t affected during the procedure (e.g., which gateways remain available, whether existing VPN sessions are interrupted)
  • Pre-flight Checklist — A condensed checklist version of the “Before You Begin” section, useful for operators who have run the procedure before and need a quick reference
  • Related Guides — Links to Configuration Guides that must be completed before this procedure, or that are commonly needed afterward

​
Tone & voice

Precise and safety-conscious. Operational tasks often run in production environments where mistakes have real consequences. Errors, warnings, and constraints must be stated explicitly and prominently — not buried in prose. For upgrade guides specifically: use <Warning> callouts liberally for any step that is irreversible, any compatibility constraint that would cause a failure, and any action that causes service interruption. For troubleshooting guides: write from the reader’s perspective — they are in a stressful situation and need clear signal. Use exact error text. State what the resolution does and why it works, not just what to click.

​
Length guidance

  • Upgrade Guides: 150–400 lines. These must be comprehensive enough to be followed safely but focused enough to be read in full before starting.
  • Troubleshooting Guides: 300–800 lines. These are reference documents covering many scenarios — length is acceptable if well-structured with clear H2 headings that make scanning easy.
  • Maintenance Guides: 80–200 lines. These are typically focused, single-task procedures.

​
Frontmatter

See Frontmatter Standards for field definitions and formatting rules. Title naming conventions by sub-type:
  • Upgrade: Upgrade [Component] from [Version] to [Version] or [Component] Upgrade Procedure. Example: Controller and Gateway Upgrade Procedure.
  • Troubleshooting: Troubleshoot [Component or Feature] or Diagnose [Problem Type]. Name the problem domain, not a specific error. Example: Troubleshoot Gateway Upgrade Errors.
  • Maintenance: Imperative form naming the task. Example: Back Up the Aviatrix Controller.

​
Mintlify components

See Style Guide for component definitions and usage rules. Use <Warning> for irreversible steps, <Steps> for high-level phase breakdown, and <Tabs> when the same procedure differs significantly by cloud provider or deployment type. Use code blocks for log output and error messages.

​
Linking

  • Link in from: No fixed upstream relationship — other documents may link here when relevant
  • Link out to: Aviatrix Support portal for escalation; Release Notices or other reference material when relevant to the procedure

​
Dos and don’ts