Add Boilerplate Sample Setup (#4)

Author: simonkurtz-MSFT

.gitignore

@@ -9,9 +9,6 @@ env/
 # Jupyter
 .ipynb_checkpoints/
 
-# VS Code
-.vscode/
-
 # Azure
 .azure/
 
@@ -26,7 +23,8 @@ labs-in-progress/
 # Exclude sensitive or generated files
 .env
 
-
 # Coverage data and reports
 .coverage
 tests/python/htmlcov/
+
+shared/bicep/modules/**/*.json

.vscode/README.md

@@ -0,0 +1,3 @@
+## Fixing Pylance unresolved import warnings
+
+Follow [this documentation](https://github.com/microsoft/pylance-release/blob/main/TROUBLESHOOTING.md#unresolved-import-warnings).

.vscode/settings.json

@@ -0,0 +1,21 @@
+{
+    "python.analysis.extraPaths": [
+        "${workspaceFolder}/shared/python"
+    ],
+    "python.analysis.completeFunctionParens": true,
+    "python.analysis.autoIndent": true,
+    "python.analysis.diagnosticSeverityOverrides": {
+        "reportDuplicateImport": "warning",
+        "reportUndefinedVariable": "information",
+        "reportUnusedVariable": "information"
+    },
+    "python.envFile": "${workspaceFolder}/.env",
+    "plantuml.render": "Local",
+    "plantuml.exportFormat": "svg",
+    "terminal.integrated.env.windows": {
+        "PATH": "${env:PATH}"
+    },
+    "plantuml.java": "C:\\Program Files\\OpenJDK\\jdk-22.0.2\\bin\\java.exe",
+    "plantuml.diagramsRoot": "diagrams/src",
+    "plantuml.exportOutDir": "diagrams/out"
+}

README.md

@@ -79,6 +79,18 @@ The first time you run a Jupyter notebook, you'll be asked to install the Jupyte
 
 Now that infrastructure and sample have been stood up, you can experiment with the policies, make requests against APIM, etc.
 
+### Adding a Sample
+
+Adding a new sample is relatively straight-forward.
+
+1. Create a new feature branch for the new sample.
+1. Copy the `/samples/_TEMPLATE` folder.
+1. Rename the copied folder to a name representative of the sample (e.g. "load-balancing", "authX", etc.)
+1. Change the `create.ipynb` and `main.bicep` files. Look for the brackets (`[ ]`) brackets for specific inputs.
+1. Add any policy.xml files to the same folder if they are specific to this sample. If they are to be reused, place them into the `/shared/apim-policies` folder instead.
+1. Test the sample with all supported infrastructures.
+1. Create a pull request for merge.
+
 ---
 
 ## Development
@@ -89,7 +101,6 @@ The repo uses the bicep linter and has rules defined in `bicepconfig.json`. See
 
 We welcome contributions! Please consider forking the repo and creating issues and pull requests to share your samples. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details. Thank you! 
 
-
 ### Testing & Code Coverage
 
 Python modules in `shared/python` are covered by comprehensive unit tests located in `tests/python`. All tests use [pytest](https://docs.pytest.org/) and leverage modern pytest features, including custom markers for unit and HTTP tests.

infrastructure/afd-apim/README.md

@@ -1,4 +1,3 @@
-
 # Front Door & API Management & Container Apps Infrastructure
 
 Secure architecture that takes all traffic off the public Internet once Azure Front Door is traversed. This is due to Front Door's use of a private link to Azure API Management.

infrastructure/afd-apim/create.ipynb

@@ -45,12 +45,11 @@
     "# 3) Define the APIs and their operations and policies\n",
     "\n",
     "# Policies\n",
-    "default_policy_xml      = utils.policy_xml_replacement(DEFAULT_XML_POLICY_PATH)\n",
     "hello_world_policy_xml  = utils.policy_xml_replacement(HELLO_WORLD_XML_POLICY_PATH)\n",
     "\n",
     "# Hello World (Root)\n",
     "api_hwroot_get  = GET_APIOperation('This is a GET for API 1', hello_world_policy_xml)\n",
-    "api_hwroot      = API('hello-world', 'Hello World', '', 'This is the root API for Hello World', default_policy_xml, [api_hwroot_get])\n",
+    "api_hwroot      = API('hello-world', 'Hello World', '', 'This is the root API for Hello World', operations = [api_hwroot_get])\n",
     "\n",
     "apis: List[API] = [api_hwroot]\n",
     "\n",
@@ -63,16 +62,16 @@
     "    aca_backend_pool_policy_xml = utils.policy_xml_replacement(ACA_BACKEND_POOL_XML_POLICY_PATH)\n",
     "\n",
     "    # Hello World (ACA Backend 1)\n",
-    "    api_hwaca_1_get = GET_APIOperation('This is a GET for Hello World on ACA Backend 1', default_policy_xml)\n",
-    "    api_hwaca_1 = API('hello-world-aca-1', 'Hello World (ACA 1)', '/aca-1', 'This is the ACA API for Backend 1', aca_backend_1_policy_xml, [api_hwaca_1_get])\n",
+    "    api_hwaca_1_get = GET_APIOperation('This is a GET for Hello World on ACA Backend 1')\n",
+    "    api_hwaca_1 = API('hello-world-aca-1', 'Hello World (ACA 1)', '/aca-1', 'This is the ACA API for Backend 1', policyXml = aca_backend_1_policy_xml, operations = [api_hwaca_1_get])\n",
     "\n",
     "    # Hello World (ACA Backend 2)\n",
-    "    api_hwaca_2_get = GET_APIOperation('This is a GET for Hello World on ACA Backend 2', default_policy_xml)\n",
-    "    api_hwaca_2 = API('hello-world-aca-2', 'Hello World (ACA 2)', '/aca-2', 'This is the ACA API for Backend 2', aca_backend_2_policy_xml, [api_hwaca_2_get])\n",
+    "    api_hwaca_2_get = GET_APIOperation('This is a GET for Hello World on ACA Backend 2')\n",
+    "    api_hwaca_2 = API('hello-world-aca-2', 'Hello World (ACA 2)', '/aca-2', 'This is the ACA API for Backend 2', policyXml = aca_backend_2_policy_xml, operations = [api_hwaca_2_get])\n",
     "\n",
     "    # Hello World (ACA Backend Pool)\n",
-    "    api_hwaca_pool_get = GET_APIOperation('This is a GET for Hello World on ACA Backend Pool', default_policy_xml)\n",
-    "    api_hwaca_pool = API('hello-world-aca-pool', 'Hello World (ACA Pool)', '/aca-pool', 'This is the ACA API for Backend Pool', aca_backend_pool_policy_xml, [api_hwaca_pool_get])\n",
+    "    api_hwaca_pool_get = GET_APIOperation('This is a GET for Hello World on ACA Backend Pool')\n",
+    "    api_hwaca_pool = API('hello-world-aca-pool', 'Hello World (ACA Pool)', '/aca-pool', 'This is the ACA API for Backend Pool', policyXml = aca_backend_pool_policy_xml, operations = [api_hwaca_pool_get])\n",
     "\n",
     "    # Add ACA APIs to the existing apis array\n",
     "    apis += [api_hwaca_1, api_hwaca_2, api_hwaca_pool]\n",
@@ -111,7 +110,7 @@
     "\n",
     "# 3) Print a deployment summary, if successful; otherwise, exit with an error\n",
     "if not output.success:\n",
-    "    exit('Deployment failed')\n",
+    "    raise SystemExit('Deployment failed')\n",
     "\n",
     "if output.success and output.json_data:\n",
     "    apim_service_id     = output.get('apimServiceId', 'APIM Service Id')\n",
@@ -219,7 +218,7 @@
     "\n",
     "# 3) Print a single, clear deployment summary if successful\n",
     "if not output.success:\n",
-    "    exit('Deployment failed')\n",
+    "    raise SystemExit('Deployment failed')\n",
     "    \n",
     "if output.success and output.json_data:\n",
     "    apim_gateway_url = output.get('apimResourceGatewayURL', 'APIM API Gateway URL')\n",

infrastructure/apim-aca/README.md

@@ -1,4 +1,3 @@
-
 # API Management & Container Apps Infrastructure
 
 This architecture secures API traffic by routing requests through Azure API Management, which is integrated with Azure Container Apps for backend processing. Telemetry is sent to Azure Monitor for observability.

infrastructure/apim-aca/create.ipynb

@@ -45,27 +45,26 @@
     "# 3) Define the APIs and their operations and policies\n",
     "\n",
     "# Policies\n",
-    "default_policy_xml          = utils.policy_xml_replacement(DEFAULT_XML_POLICY_PATH)\n",
     "hello_world_policy_xml      = utils.policy_xml_replacement(HELLO_WORLD_XML_POLICY_PATH)\n",
     "aca_backend_1_policy_xml    = utils.policy_xml_replacement(ACA_BACKEND_1_XML_POLICY_PATH)\n",
     "aca_backend_2_policy_xml    = utils.policy_xml_replacement(ACA_BACKEND_2_XML_POLICY_PATH)\n",
     "aca_backend_pool_policy_xml = utils.policy_xml_replacement(ACA_BACKEND_POOL_XML_POLICY_PATH)\n",
     "\n",
     "# Hello World (Root)\n",
     "api_hwroot_get = GET_APIOperation('This is a GET for Hello World in the root', hello_world_policy_xml)\n",
-    "api_hwroot  = API('hello-world', 'Hello World', '', 'This is the root API for Hello World', default_policy_xml, [api_hwroot_get])\n",
+    "api_hwroot  = API('hello-world', 'Hello World', '', 'This is the root API for Hello World', operations = [api_hwroot_get])\n",
     "\n",
     "# Hello World (ACA Backend 1)\n",
-    "api_hwaca_1_get = GET_APIOperation('This is a GET for Hello World on ACA Backend 1', default_policy_xml)\n",
-    "api_hwaca_1 = API('hello-world-aca-1', 'Hello World (ACA 1)', '/aca-1', 'This is the ACA API for Backend 1', aca_backend_1_policy_xml, [api_hwaca_1_get])\n",
+    "api_hwaca_1_get = GET_APIOperation('This is a GET for Hello World on ACA Backend 1')\n",
+    "api_hwaca_1 = API('hello-world-aca-1', 'Hello World (ACA 1)', '/aca-1', 'This is the ACA API for Backend 1', policyXml = aca_backend_1_policy_xml, operations = [api_hwaca_1_get])\n",
     "\n",
     "# Hello World (ACA Backend 2)\n",
-    "api_hwaca_2_get = GET_APIOperation('This is a GET for Hello World on ACA Backend 2', default_policy_xml)\n",
-    "api_hwaca_2 = API('hello-world-aca-2', 'Hello World (ACA 2)', '/aca-2', 'This is the ACA API for Backend 2', aca_backend_2_policy_xml, [api_hwaca_2_get])\n",
+    "api_hwaca_2_get = GET_APIOperation('This is a GET for Hello World on ACA Backend 2')\n",
+    "api_hwaca_2 = API('hello-world-aca-2', 'Hello World (ACA 2)', '/aca-2', 'This is the ACA API for Backend 2', policyXml = aca_backend_2_policy_xml, operations = [api_hwaca_2_get])\n",
     "\n",
     "# Hello World (ACA Backend Pool)\n",
-    "api_hwaca_pool_get = GET_APIOperation('This is a GET for Hello World on ACA Backend Pool', default_policy_xml)\n",
-    "api_hwaca_pool = API('hello-world-aca-pool', 'Hello World (ACA Pool)', '/aca-pool', 'This is the ACA API for Backend Pool', aca_backend_pool_policy_xml, [api_hwaca_pool_get])\n",
+    "api_hwaca_pool_get = GET_APIOperation('This is a GET for Hello World on ACA Backend Pool')\n",
+    "api_hwaca_pool = API('hello-world-aca-pool', 'Hello World (ACA Pool)', '/aca-pool', 'This is the ACA API for Backend Pool', policyXml = aca_backend_pool_policy_xml, operations = [api_hwaca_pool_get])\n",
     "\n",
     "# APIs Array\n",
     "apis: List[API] = [api_hwroot, api_hwaca_1, api_hwaca_2, api_hwaca_pool]\n",
@@ -101,7 +100,7 @@
     "\n",
     "# 3) Check the deployment outputs\n",
     "if not output.success:\n",
-    "    exit('Deployment failed')\n",
+    "    raise SystemExit('Deployment failed')\n",
     "\n",
     "if output.success and output.json_data:\n",
     "    apim_gateway_url    = output.get('apimResourceGatewayURL', 'APIM API Gateway URL')\n",

infrastructure/simple-apim/README.md

@@ -1,4 +1,3 @@
-
 # Simple API Management Infrastructure
 
 This architecture provides a basic API gateway using Azure API Management, suitable for simple scenarios where secure API exposure and basic observability are required.

infrastructure/simple-apim/create.ipynb

@@ -43,12 +43,11 @@
     "# 3) Define the APIs and their operations and policies\n",
     "\n",
     "# Policies\n",
-    "default_policy_xml      = utils.policy_xml_replacement(DEFAULT_XML_POLICY_PATH)\n",
     "hello_world_policy_xml  = utils.policy_xml_replacement(HELLO_WORLD_XML_POLICY_PATH)\n",
     "\n",
     "# Hello World (Root)\n",
     "api_hwroot_get = GET_APIOperation('This is a GET for API 1', hello_world_policy_xml)\n",
-    "api_hwroot = API('hello-world', 'Hello World', '', 'This is the root API for Hello World', default_policy_xml, [api_hwroot_get])\n",
+    "api_hwroot = API('hello-world', 'Hello World', '', 'This is the root API for Hello World', operations = [api_hwroot_get])\n",
     "\n",
     "# APIs Array\n",
     "apis: List[API] = [api_hwroot]\n",
@@ -84,7 +83,7 @@
     "\n",
     "# 3) Check the deployment outputs\n",
     "if not output.success:\n",
-    "    exit('Deployment failed')\n",
+    "    raise SystemExit('Deployment failed')\n",
     "\n",
     "if output.success and output.json_data:\n",
     "    apim_gateway_url = output.get('apimResourceGatewayURL', 'APIM API Gateway URL')\n",