Add NVA Routing sample: route APIM outbound traffic through Azure Firewall in a hub/spoke topology (#181)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: simonkurtz-MSFT <84809797+simonkurtz-MSFT@users.noreply.github.com>
Co-authored-by: Simon Kurtz <simonkurtz@microsoft.com>

Author: Copilot

.github/copilot-instructions.md

@@ -54,6 +54,8 @@ Uniformity, clarity, and ease of use are paramount across all infrastructures an
 - **Keep README structure uniform.** Infrastructure READMEs and sample READMEs each follow their own standard layout (see the guidelines below). Readers should be able to predict where to find objectives, configuration steps, and execution instructions.
 - **Reuse shared utilities.** Use `NotebookHelper`, `InfrastructureNotebookHelper`, `ApimRequests`, `ApimTesting`, and shared Bicep modules rather than inventing ad-hoc alternatives. Shared code is the single best tool for enforcing uniformity.
 - **Mirror tone and depth.** Similar sections across artefacts should use similar levels of detail. If one sample's README explains configuration in three sentences, another sample of comparable complexity should do the same.
+- **Sort samples alphabetically.** Wherever samples are listed (README tables, landing page cards, JSON-LD structured data, diagrams, AGENTS.md), they must appear in alphabetical order by their display name. Infrastructures keep their current deliberate ordering.
+- **Use consistent sample display names.** The display name used for a sample in README tables, landing page cards, JSON-LD, and compatibility diagrams must be identical. The canonical name is the one shown in the compatibility-matrix SVG diagram (e.g. "Costing", not "Costing & Showback"; "OAuth 3rd-Party", not "Credential Manager (with Spotify)"). Longer descriptions belong in the Description column or card body text, not in the name.
 - **Validate against peers.** Before finalising a new infrastructure or sample, compare it side-by-side with at least one existing peer to identify structural or stylistic drift.
 
 ## General Coding Guidelines
@@ -423,6 +425,8 @@ Check `docs/README.md` for local preview instructions and styling notes. The pag
 - The Draw.io diagrams were created with the [Azure Draw.io MCP Server](https://github.com/simonkurtz-MSFT/drawio-mcp-server).
 - Keep diagrams simple. For Azure, include major components, not individual aspects of components. For example, there is no need for individual policies in WAFs or APIs in API Management, Smart Detector Alert Rules, etc.
 - Less is more. Don't be too verbose in the diagrams.
+- Sample names in compatibility-matrix diagrams are the canonical display names. README tables, landing page cards, and JSON-LD entries must use the same names. When adding or renaming a sample, update the diagram and all listings together.
+- Samples in compatibility-matrix diagrams must be listed in alphabetical order by display name.
 - Never include subscription IDs, resource group names, or any other sensitive information in the diagrams. That data is not relevant.
 
 ### KQL (Kusto Query Language) Instructions

AGENTS.md

@@ -27,9 +27,10 @@ This repository provides resources to deploy Azure API Management infrastructure
 │   ├── authX-pro/           # Advanced auth with policy fragments
 │   ├── azure-maps/          # Azure Maps integration
 │   ├── costing/             # APIM costing and showback
+│   ├── egress-control/      # Egress control via NVA routing
 │   ├── general/             # Basic policy demonstrations
 │   ├── load-balancing/      # Backend pool load balancing
-│   ├── oauth-3rd-party/     # Credential Manager (Spotify example)
+│   ├── oauth-3rd-party/     # OAuth 3rd-party (Spotify example)
 │   └── secure-blob-access/  # Valet key pattern for blob storage
 │
 ├── shared/                  # Reusable components

README.md

@@ -67,10 +67,11 @@ It's quick and easy to get started!
 | [AuthX][sample-authx]                                       | Authentication and role-based authorization in a mock HR API.                                                       | All infrastructures           |
 | [AuthX Pro][sample-authx-pro]                               | Authentication and role-based authorization in a mock product with multiple APIs and policy fragments.              | All infrastructures           |
 | [Azure Maps][sample-azure-maps]                             | Proxying calls to Azure Maps with APIM policies.                                                                    | All infrastructures           |
-| [Costing & Showback][sample-costing]                        | Track and allocate API costs per business unit using APIM subscriptions, Log Analytics, and Cost Management.         | All infrastructures           |
-| [Credential Manager (with Spotify)][sample-oauth-3rd-party] | Authenticate with APIM which then uses its Credential Manager with Spotify's REST API.                              | All infrastructures           |
+| [Costing][sample-costing]                                   | Track and allocate API costs per business unit using APIM subscriptions, Log Analytics, and Cost Management.         | All infrastructures           |
+| [Egress Control][sample-egress-control]                     | Control APIM outbound internet traffic by routing it through a Network Virtual Appliance (NVA) in a hub/spoke topology. | appgw-apim, appgw-apim-pe     |
 | [General][sample-general]                                   | Basic demo of APIM sample setup and policy usage.                                                                   | All infrastructures           |
 | [Load Balancing][sample-load-balancing]                     | Priority and weighted load balancing across backends.                                                               | apim-aca, afd-apim-pe         |
+| [OAuth 3rd-Party][sample-oauth-3rd-party]                   | Authenticate with APIM which then uses its Credential Manager with Spotify's REST API.                              | All infrastructures           |
 | [Secure Blob Access][sample-secure-blob-access]             | Secure blob access via the [valet key pattern][valet-key-pattern].                                                  | All infrastructures           |
 </details>
 
@@ -381,6 +382,7 @@ _For much more API Management content, please also check out [APIM Love](https:/
 [sample-costing]: ./samples/costing/README.md
 [sample-general]: ./samples/general/README.md
 [sample-load-balancing]: ./samples/load-balancing/README.md
+[sample-egress-control]: ./samples/egress-control/README.md
 [sample-oauth-3rd-party]: ./samples/oauth-3rd-party/README.md
 [sample-secure-blob-access]: ./samples/secure-blob-access/README.md
 [simon-kurtz]: https://github.com/simonkurtz-msft

assets/APIM-Samples-Slide-Deck.html

@@ -1015,7 +1015,7 @@ <h3>&#128218; Samples</h3>
         <ul style="list-style: none; padding: 0;">
           <li style="padding: 6px 0; font-size: 15px; color: #444; display: flex; gap: 10px; align-items: flex-start;">
             <div class="bullet" style="flex-shrink:0; width:8px; height:8px; border-radius:50%; background:#0078D4; margin-top:7px;"></div>
-            <div>8 real-world scenarios covering auth, costing, mapping, and more</div>
+            <div>9 real-world scenarios covering auth, networking, costing, and more</div>
           </li>
           <li style="padding: 6px 0; font-size: 15px; color: #444; display: flex; gap: 10px; align-items: flex-start;">
             <div class="bullet" style="flex-shrink:0; width:8px; height:8px; border-radius:50%; background:#0078D4; margin-top:7px;"></div>
@@ -1095,18 +1095,18 @@ <h4>App Gateway & APIM (VNet Injection)</h4>
   <div class="slide slide-light">
     <div class="header-bar">
       <div class="accent"></div>
-      <h2>8 Real-World Policy Samples</h2>
+      <h2>9 Real-World Policy Samples</h2>
     </div>
-    <p class="subtitle">From authentication & authorization to cost tracking and secure access patterns</p>
+    <p class="subtitle">From authentication &amp; authorization to network routing, cost tracking, and secure access patterns</p>
 
-    <div class="arch-grid" style="flex: 1;">
+    <div class="arch-grid" style="flex: 1; grid-template-columns: 1fr 1fr 1fr;">
       <div class="arch-card">
         <h4>General</h4>
-        <p>Basic APIM setup & policy usage. Perfect starting point.</p>
+        <p>Basic APIM setup &amp; policy usage. Perfect starting point.</p>
       </div>
       <div class="arch-card">
         <h4>AuthX</h4>
-        <p>JWT authentication & role-based authorization with a mock HR API.</p>
+        <p>JWT authentication &amp; role-based authorization with a mock HR API.</p>
       </div>
       <div class="arch-card">
         <h4>AuthX Pro</h4>
@@ -1117,16 +1117,20 @@ <h4>Azure Maps</h4>
         <p>Proxying calls to Azure Maps through APIM policies.</p>
       </div>
       <div class="arch-card">
-        <h4>Costing & Showback</h4>
-        <p>Track API costs per business unit via subscriptions & Log Analytics.</p>
+        <h4>Costing &amp; Showback</h4>
+        <p>Track API costs per business unit via subscriptions &amp; Log Analytics.</p>
       </div>
       <div class="arch-card">
         <h4>Credential Manager</h4>
         <p>APIM Credential Manager with Spotify's REST API.</p>
       </div>
       <div class="arch-card">
         <h4>Load Balancing</h4>
-        <p>Priority & weighted load balancing across backends.</p>
+        <p>Priority &amp; weighted load balancing across backends.</p>
+      </div>
+      <div class="arch-card">
+        <h4>Egress Control</h4>
+        <p>Route APIM outbound traffic through Azure Firewall in a hub/spoke topology.</p>
       </div>
       <div class="arch-card">
         <h4>Secure Blob Access</h4>
@@ -1414,7 +1418,7 @@ <h4 style="color: #50E6FF;">Educate</h4>
       <div class="summary-item">
         <div class="big-icon">&#9889;</div>
         <h4 style="color: #50E6FF;">Empower</h4>
-        <p>8 real-world samples with guided Jupyter notebooks and à la carte flexibility.</p>
+        <p>9 real-world samples with guided Jupyter notebooks and à la carte flexibility.</p>
       </div>
       <div class="summary-item">
         <div class="big-icon">&#128640;</div>