> ## 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.

# Smart Gateways

> An overview of Smart Gateways, how it is built, how it works, its key capabilities, and when to use it.

<Warning>Smart Gateways is a **Preview** feature in Controller 10.1.</Warning>

## Overview

Smart Gateways moves overlay route resolution from the centralized Controller to
the gateways themselves. Each gateway can respond to tunnel and peer failures
locally without waiting for a Controller roundtrip, and continues to update its
forwarding table even if communication with the Controller is lost. Use Smart
Gateways when your fabric requires faster failure convergence or continued
routing survivability when the connection to the Controller is lost.

## Design

### Core Design

In the centralized model, the Controller computes all overlay routes and pushes
them to every gateway. When a tunnel or gateway fails, the Controller must
detect the event, recompute routes, and distribute updates. During that window,
traffic can blackhole. If the Controller is unreachable, gateways are stuck with
stale routes indefinitely.

Smart Gateways solves this by giving each gateway its own view of peer
reachability. Each gateway tracks which peers are up through a BGP Labeled
Unicast (BGP-LU) underlay mesh. The Controller still defines overlay route
policy, but gateways no longer depend on it for real-time failure response.

### How It Works

Smart Gateways adds two layers on top of the existing Aviatrix data plane:

**Underlay Mesh.** Each gateway forms BGP-LU sessions with its peers. The mesh
continuously tracks which peer gateways are reachable. Sessions use a 5-second
keepalive and a 15-second hold timer.

**Route Resolver.** Each gateway receives overlay route mappings from the
Controller and cross-references them against underlay reachability. When a peer
becomes unreachable, the gateway removes affected next-hops from its forwarding
table locally. The gateway also withdraws BGP advertisements for destinations
that no longer have any viable overlay path (FRR withdrawal), signaling peer
gateways to re-converge without waiting for the Controller. When the Route
Resolver is active, it is the sole component that writes routes to the gateway
forwarding table.

### Operation Model

How quickly the gateway converges depends on the failure type:

| Failure type                | What happens                                                                                                                    | Expected timeline                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Active tunnel link down** | Once the tunnel is detected as down, the gateway fails over to the HA path automatically. No Route Resolver involvement needed. | Sub-second after detection                                                       |
| **Gateway or peer failure** | The BGP-LU hold timer expires and the Route Resolver removes the unreachable next-hops from the forwarding table.               | Approximately 20 seconds on large fabrics (15-second hold timer plus processing) |

<Note>
  In cloud environments, there is no physical link-down event. Tunnel failure is
  detected by mechanisms such as Dead Peer Detection (DPD) or BFD, which adds
  convergence time before the sub-second kernel failover begins. Do not assume
  zero-loss failover.
</Note>

When both the active and HA paths for a destination are unreachable, the Route
Resolver selects an alternate path through remaining transit gateways so that
traffic continues to flow during multi-failure scenarios.

## Key Features

### Gateway-Local Convergence

Each gateway detects failures through the BGP-LU underlay mesh and updates its
own forwarding table without waiting for the Controller.

* Removes unreachable next-hops on failure detection
* Withdraws BGP advertisements for unreachable destinations (FRR withdrawal),
  causing peer gateways to stop forwarding traffic for those CIDRs to this
  gateway
* Restores routes automatically when peers recover

### Progressive Enablement

Smart Gateways uses a three-flag hierarchy that you enable incrementally. Each
flag builds on the previous one, and you can verify the fabric at each stage
before proceeding.

| Flag                                    | Scope             | What it enables                                                                                      | Depends on                                                      |
| --------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| **Smart Gateways** (Flag 1)             | Controller-wide   | Master switch for the entire feature. Disabling forces Flags 2 and 3 off everywhere.                 | None                                                            |
| **Underlay Mesh Connectivity** (Flag 2) | Per gateway group | BGP-LU sessions between gateways. Gateways begin tracking peer reachability.                         | Flag 1 enabled                                                  |
| **Route Resolver** (Flag 3)             | Per gateway group | Gateway-local route resolution. The gateway takes over forwarding table updates from the Controller. | Flag 1 enabled **and** Flag 2 enabled on **all** gateway groups |

The flags enforce a strict dependency chain: disabling Flag 1 forces Flags 2 and
3 off on all gateway groups. Disabling Flag 2 forces Flag 3 off for that group.
Enabling Flag 3 requires Flag 2 to be enabled on all groups in the fabric, not
only the target group.

<Info>
  For enablement steps, see the Smart Gateways section in the CoPilot UI
  reference.
</Info>

### Alternate Path Selection

When both the active and HA paths for a destination fail, the Route Resolver
selects an alternate path through remaining transit gateways, providing
continued reachability without Controller intervention.

### Network Segmentation Support

When Network Segmentation is enabled, the Route Resolver maintains separate
route tables per network domain for each gateway group.

### Route Type Bypass

Routes learned through BGP over IPsec, BGP over GRE, BGP over LAN, and Static
External connections are not subject to Route Resolver pruning. These connection
types have next-hops outside the BGP-LU underlay mesh, so their routes are
installed unchanged.

### Supported Gateway Types

Smart Gateways in 10.1 Preview supports transit gateways, BGP-enabled spoke
gateways, Edge as Spoke (EAS), and Edge as Transit (EAT).

## When to Use

### Large Multi-Region Fabrics

In fabrics that span many regions, the Controller roundtrip for route
recomputation after a failure can take tens of seconds. Smart Gateways reduces
this to local convergence bounded by BGP-LU timers.

### Controller-Resilient Routing

If the Controller becomes temporarily unreachable (for example, during a network
partition), gateways with Smart Gateways enabled continue to respond to failures
using their local BGP-LU state. Without Smart Gateways, gateways cannot update
their routing tables until the Controller reconnects.

### Fabrics with Strict Convergence Requirements

For deployments where the time between a failure and traffic recovery must be
minimized, Smart Gateways provides sub-second kernel failover once a local
tunnel failure is detected, and approximately 20-second convergence for peer
failures detected by BGP-LU.

## Best Practices

* **Enable flags incrementally.** Start with Flag 1 (controller-wide), then
  enable Flag 2 on one gateway group and verify BGP-LU sessions are established
  before rolling out to additional groups. Enable Flag 3 only after Flag 2 is
  active on all groups.

* **Use appropriately sized instances for spoke gateways.** The Route Resolver
  adds memory overhead. Small-sized spoke gateways may experience memory
  pressure. Use medium or larger instance sizes where Smart Gateways is active.

* **Verify underlay mesh health before enabling the Route Resolver.** With Flag
  2 enabled, confirm that all expected BGP-LU sessions are established and that
  peer counts match your expected topology before enabling Flag 3.

* **Plan for the emergency disable path.** Disable Flag 1 to force all flags off
  everywhere. To re-enable, work top-down: Flag 1 first, then Flag 2 on each
  group, then Flag 3.

* **Monitor with CLI and API in 10.1.** The CoPilot Smart Gateway Health page
  requires Controller 10.2 or later. In 10.1, use CLI and API commands for
  diagnostics.

## Limitations

* **Preview only.** GA is targeted for a future release.
* **No CoPilot diagnostics page in 10.1.** The Smart Gateway Health page
  requires Controller 10.2 or later.
* **Terraform support is partial.** The `aviatrix_config_feature` resource can
  toggle the fabric-wide flag (Flag 1) only. Per-group flags (Flags 2 and 3)
  require direct API calls.
* **Pruning suspension is not observable.** During underlay convergence events
  (such as a BGP-LU peer restart), the Route Resolver temporarily suspends
  next-hop pruning as a safety measure. There is no metric or log indicating
  when pruning is suspended.
* **Convergence is not uniformly sub-second.** Sub-second kernel failover
  applies only after a local tunnel failure is detected. Detection itself
  depends on DPD or BFD timers and adds convergence time. Peer failures detected
  by BGP-LU take approximately 20 seconds on large fabrics.

## Related Features

| Feature                                                                                                                    | Relationship                                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Less-Disruptive Gateway Resize and Upgrade (Preview)                                                                       | Make Before Break uses the drain/undrain mechanism that Smart Gateways also builds on. Both are independent Preview features in 10.1.                           |
| <a href={"/docs/enterprise/" + "10.1" + "/concepts-architectures/components/connectivity/activemesh-about"}>ActiveMesh</a> | ActiveMesh provides active-active forwarding across primary and HA gateways. Smart Gateways adds gateway-local convergence on top of the ActiveMesh data plane. |