+
+**The fastest way to get started is using our pre-configured development environment.**
----
+Each supported Python version has its own dev container, providing you with a more tailored environment that hopefully more closely resembles your own workloads.
-#### Using Dev Container (Recommended)
+**GitHub Codespaces**: Click the green "Code" button โ "Codespaces" โ "..." โ "New with options..." โ "Dev container configuration" (select Python version but ignore *Default project configuration*) โ "Create codespace"
-If you're using the dev container (GitHub Codespaces or VS Code Dev Containers):
+
+
+**VS Code Dev Containers**: Alternatively, you can run the dev container locally by installing the [Dev Containers extension][vscode-devcontainers], then selecting "Reopen in Container".
1. Open the repository in the dev container environment
2. Wait for the automatic setup to complete (includes interactive Azure CLI configuration)
@@ -191,80 +112,56 @@ If you're using the dev container (GitHub Codespaces or VS Code Dev Containers):
- Verify your authentication context: `az account show`
5. Verify your Azure setup by executing [shared/jupyter/verify-az-account.ipynb](shared/jupyter/verify-az-account.ipynb)
-#### Manual Local Setup
-
-If you're setting up locally without the dev container:
+All prerequisites are automatically installed and configured.
-##### Quick Setup (Recommended)
+๐ **For detailed setup information, troubleshooting, and optimization details, see [Dev Container Documentation](.devcontainer/README.md)**
+
-1. **Create Python Environment**: In VS Code, use Ctrl+Shift+P โ "Python: Create Environment" โ "Venv" โ Select Python version โ Check requirements.txt
-2. **Complete Environment Setup**: Run the automated setup script:
- ```bash
- python setup/local_setup.py --complete-setup
- ```
- For help and available options, run without arguments:
- ```bash
- python setup/local_setup.py
- ```
-3. **Restart VS Code** to apply all settings
-4. **Sign in to Azure**: `az login --tenant
+
+**VS Code Dev Containers**: Alternatively, you can run the dev container locally by installing the [Dev Containers extension][vscode-devcontainers], then selecting "Reopen in Container".
1. Open the repository in the dev container environment
2. Wait for the automatic setup to complete (includes interactive Azure CLI configuration)
@@ -191,80 +112,56 @@ If you're using the dev container (GitHub Codespaces or VS Code Dev Containers):
- Verify your authentication context: `az account show`
5. Verify your Azure setup by executing [shared/jupyter/verify-az-account.ipynb](shared/jupyter/verify-az-account.ipynb)
-#### Manual Local Setup
-
-If you're setting up locally without the dev container:
+All prerequisites are automatically installed and configured.
-##### Quick Setup (Recommended)
+๐ **For detailed setup information, troubleshooting, and optimization details, see [Dev Container Documentation](.devcontainer/README.md)**
+
-That's it! Your local environment now matches the dev container experience with:
-- โ
Standardized "APIM Samples Python 3.12" Jupyter kernel
-- โ
Automatic notebook kernel selection
-- โ
Python path configured for shared modules
-- โ
VS Code optimized for the project
+#### ๐ Prerequisites
-When you open any `.ipynb` notebook, it will automatically use the correct kernel and all imports will work seamlessly.
-
-**๐ Verify Setup**: Run `python setup/verify_local_setup.py` to confirm everything is working correctly.
+These prerequisites apply broadly across all infrastructure and samples. If there are specific deviations, expect them to be noted there.
-##### Manual Step-by-Step Setup
+- [Python][python] **3.12, 3.13, and 3.14 are all supported**
+- [VS Code][vscode] installed with the [Jupyter notebook extension][vscode-jupyter] enabled
+- [Azure CLI][azure-cli-install] installed
+- [Azure Bicep][azure-bicep-install] installed
+- [An Azure Subscription][azure-free] with Owner or Contributor+UserAccessAdministrator permissions. Execute [Verify Azure Account][verify-az-account-notebook] to verify.
+- **Azure Authentication**: Sign in to Azure with Azure CLI using the specific tenant and subscription you want to work with:
+ - To log in to a specific tenant: `az login --tenant `
+ - To set a specific subscription: `az account set --subscription `
+ - To verify your current context: `az account show`
+ - See the [Azure CLI authentication guide][azure-cli-auth] for more options
-If you prefer manual setup or the automated script doesn't work:
+#### Manual Local Setup
-1. Open VS Code.
-1. Invoke the _Command Palette_ via the _View_ menu or a shortcut (on Windows: Ctrl + Shift + P, on Mac: CMD + Shift + P).
-1. Select _Python: Create Environment_.
-1. Select _Venv_ as we want a local virtual environment.
-1. Select the desired, installed Python version.
-1. Check _requirements.txt_ to install the Python dependencies we need for this repo, then press _OK_. The install may take a few minutes. You can check on progress in the _OUTPUT_ window (select `Python`).
-1. Verify the virtual environment is set up. You should see a new _.venv_ directory with a _pyveng.cfg_ file and the Python version you selected earlier.
-1. Set up the project environment:
- ```bash
- python setup/local_setup.py --generate-env
- python setup/local_setup.py --setup-kernel
- python setup/local_setup.py --setup-vscode
- ```
-1. **Restart VS Code** to ensure all environment settings are loaded properly.
+1. **Create Python Environment**: In VS Code, use Ctrl+Shift+P โ "Python: Create Environment" โ "Venv" โ Select Python version โ Check requirements.txt
+ The install may take a few minutes. You can check on progress in the _OUTPUT_ window (select `Python`).
+1. **Complete Environment Setup**: Open a terminal and start the [Developer CLI](#-developer-cli), then select `Complete environment setup`.
+3. **Restart VS Code** to apply all settings
+4. **Sign in to Azure**: `az login --tenant ` and `az account set --subscription `
+5. **Verify local setup**: Start the Developer CLI, then select `Verify local setup`.
The first time you run a Jupyter notebook, you may be asked to install the Jupyter kernel package (ipykernel) if not already available.
+When you open any `.ipynb` notebook, it will automatically use the correct kernel and all imports will work seamlessly.
+
-#### ๐ง Troubleshooting Setup Issues
-
-If you encounter import errors (e.g., `ModuleNotFoundError: No module named 'requests'` or cannot import shared modules), try these steps:
-
-1. **Fix Python path configuration**:
- ```bash
- python setup/local_setup.py --generate-env
- ```
-
-2. **Verify setup**:
- ```bash
- python setup/verify_local_setup.py
- ```
+## ๐ Sample Deployments
-3. **Restart VS Code** after running the above commands.
+1. Open the desired sample's `create.ipynb` file.
+1. Optional: Adjust the parameters under the `User-defined Parameters` header, if desired.
+1. Execute the `create.ipynb` Jupyter notebook via `Run All`.
-4. **Check Python interpreter**: Use `Ctrl+Shift+P` โ "Python: Select Interpreter" and choose your `.venv` interpreter.
+> A supported infrastructure does not yet need to exist before the sample is executed. The notebook will determine the current state and present you with options to create or select a supported infrastructure, if necessary.
-For detailed troubleshooting of setup issues, see [Import Troubleshooting Guide][import-troubleshooting].
+Now that infrastructure and sample have been stood up, you can experiment with the policies, make requests against APIM, etc.
----
## ๐ Logging and Output
-The Python helpers in this repo use standard-library `logging` (not ad-hoc `print()`), so you can control verbosity via environment variables.
+The Python helpers in this repo use standard-library `logging`, empowering you to control verbosity via environment variables in the root `.env` file. This file is created via the APIM Samples Developer CLI.
- `APIM_SAMPLES_LOG_LEVEL`: Controls the overall verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`). Default: `INFO`.
- When set to `DEBUG`, the Azure CLI runner in [shared/python/azure_resources.py](shared/python/azure_resources.py) will also add `--debug` to simple `az ...` commands.
@@ -272,21 +169,10 @@ The Python helpers in this repo use standard-library `logging` (not ad-hoc `prin
๐ **For comprehensive troubleshooting including deployment errors, authentication issues, and more, see our main [Troubleshooting Guide][troubleshooting].**
-## ๐ Running a Sample
-
-1. Open the desired sample's `create.ipynb` file.
-1. Optional: Adjust the parameters under the `User-defined Parameters` header, if desired.
-1. Execute the `create.ipynb` Jupyter notebook via `Run All`.
-
-> A supported infrastructure does not yet need to exist before the sample is executed. The notebook will determine the current state and present you with options to create or select a supported infrastructure, if necessary.
-
-Now that infrastructure and sample have been stood up, you can experiment with the policies, make requests against APIM, etc.
-
----
## Troubleshooting
-Encountering issues? Check our comprehensive **[Troubleshooting Guide](TROUBLESHOOTING.md)** which covers:
+Encountering issues? Check our comprehensive **[Troubleshooting Guide](troubleshooting)**! which covers:
- **Deployment Errors** - Including the common "content already consumed" error and parameter mismatches
- **Authentication Issues** - Azure CLI login problems and permission errors
@@ -296,7 +182,6 @@ Encountering issues? Check our comprehensive **[Troubleshooting Guide](TROUBLESH
For immediate help with common errors, diagnostic commands, and step-by-step solutions, see **[TROUBLESHOOTING.md][troubleshooting]**.
----
## ๐ Repo Structure
@@ -321,8 +206,6 @@ For immediate help with common errors, diagnostic commands, and step-by-step sol
We provide several common architectural approaches to integrating APIM into your Azure ecosystem. While these are high-fidelity setups, they are not production-ready. Please refer to the [Azure API Management landing zone accelerator][apim-lza] for up-to-date production setups.
----
-
## ๐ ๏ธ Development
As you work with this repo, you will likely want to make your own customizations. There's little you need to know to be successful.
@@ -333,55 +216,11 @@ The repo uses the bicep linter and has rules defined in `bicepconfig.json`. See
### ๐ Code Quality & Linting
-The repository uses [pylint][pylint-docs] to maintain Python code quality standards. Configuration is located in `tests/python/.pylintrc`.
-
-#### Running Code Quality Checks
-
-**Using the combined check script (recommended):**
-
-This is the preferred method as it runs both linting and testing in a single command:
-
-```powershell
-# From repository root
-.\tests\python\check_python.ps1 # Run both pylint and pytest
-.\tests\python\check_python.ps1 -ShowLintReport # Include detailed pylint report
-```
-
-```bash
-# From repository root
-./tests/python/check_python.sh # Run both pylint and pytest
-./tests/python/check_python.sh --show-report # Include detailed pylint report
-```
-
-**Running pylint only:**
-
-```powershell
-# From repository root
-.\tests\python\run_pylint.ps1 # Run with default settings
-.\tests\python\run_pylint.ps1 -ShowReport # Include full detailed report
-.\tests\python\run_pylint.ps1 -Target "samples" # Analyze specific directory
-```
-
-```bash
-# From repository root
-./tests/python/run_pylint.sh # Run with default settings
-./tests/python/run_pylint.sh samples --show-report # Analyze specific directory with report
-```
-
-**Manual execution:**
-
-```powershell
-pylint --rcfile tests/python/.pylintrc shared/python
-```
-
-#### Pylint Reports
+The repository uses [pylint][pylint-docs] to maintain Python code quality standards. The configuration is located in `tests/python/.pylintrc`, and the Developer CLI supports linting.
-All pylint runs generate timestamped reports in `tests/python/pylint/reports/`:
-- **JSON format**: Machine-readable for CI/CD integration
-- **Text format**: Human-readable detailed analysis
-- **Latest symlinks**: `latest.json` and `latest.txt` always point to the most recent run
+### ๐งช Testing & Code Coverage
-The script automatically displays a **Top 10 Issues Summary** showing the most frequent code quality issues to help prioritize improvements.
+Python modules in `shared/python` are covered by comprehensive unit tests located in `tests/python`. All tests use [pytest][pytest-docs] and leverage modern pytest features, including custom markers for unit and HTTP tests. The Developer CLI supports testing.
### โ Adding a Sample
@@ -395,76 +234,11 @@ Adding a new sample is relatively straight-forward.
1. Test the sample with all supported infrastructures.
1. Create a pull request for merge.
-### ๐งช Testing & Code Coverage
-
-Python modules in `shared/python` are covered by comprehensive unit tests located in `tests/python`. All tests use [pytest][pytest-docs] and leverage modern pytest features, including custom markers for unit and HTTP tests.
-
-#### ๐ Running Tests Locally
-
-**Using the combined check script (recommended):**
-
-This is the preferred method as it runs both linting and testing:
-
-```powershell
-# From repository root
-.\tests\python\check_python.ps1
-```
-
-```bash
-# From repository root
-./tests/python/check_python.sh
-```
-
-**Running tests only:**
-
-- **PowerShell (Windows):**
- - Run all tests with coverage: `.\tests\python\run_tests.ps1` (from repository root)
-- **Shell (Linux/macOS):**
- - Run all tests with coverage: `./tests/python/run_tests.sh` (from repository root)
-
-Both scripts:
-- Run all tests in `tests/python` using pytest
-- Generate a code coverage report (HTML output in `tests/python/htmlcov`)
-- Store the raw coverage data in `tests/python/.coverage`
-
-You can also run tests manually and see details in the console:
-```sh
-pytest -v --cov=shared/python --cov-report=html:tests/python/htmlcov --cov-report=term tests/python
-```
-
-#### ๐ Viewing Coverage Reports
-
-After running tests, open `tests/python/htmlcov/index.html` in your browser to view detailed coverage information.
-
-#### ๐ท๏ธ Pytest Markers
-
-- `@pytest.mark.unit` โ marks a unit test
-- `@pytest.mark.http` โ marks a test involving HTTP/mocking
-
-Markers are registered in `pytest.ini` to avoid warnings.
-
-#### โก Continuous Integration (CI)
-
-On every push or pull request, GitHub Actions will:
-- Install dependencies
-- Run all Python tests in `tests/python` with coverage
-- Store the `.coverage` file in `tests/python`
-- Upload the HTML coverage report as a workflow artifact for download
-
-#### ๐ Additional Notes
-
-- The `.gitignore` is configured to exclude coverage output and artifacts.
-- All test and coverage features work both locally and in CI.
-
-For more details on pytest usage, see the [pytest documentation][pytest-docs-versioned].
-
----
## ๐ Supporting Resources
-The APIM team maintains an [APIM policy snippets repo][apim-snippets-repo] with use cases we have seen. They are not immediately executable samples and require integrations such as in this repo.
+The APIM team maintains an [APIM policy snippets repo][apim-snippets] with use cases we have seen. They are not immediately executable samples and require integrations such as in this repo.
----
## ๐ Acknowledgements
@@ -484,7 +258,7 @@ The original author of this project is [Simon Kurtz][simon-kurtz].
[andrew-redman]: https://github.com/anotherRedbeard
[apim-love]: https://aka.ms/apimlove
[apim-lza]: https://learn.microsoft.com/azure/cloud-adoption-framework/scenarios/app-platform/api-management/landing-zone-accelerator
-[apim-snippets-repo]: https://github.com/Azure/api-management-policy-snippets
+[apim-snippets]: https://github.com/Azure/api-management-policy-snippets
[azure-bicep-install]: https://learn.microsoft.com/azure/azure-resource-manager/bicep/install#azure-cli
[azure-cli-auth]: https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively
[azure-cli-install]: https://learn.microsoft.com/cli/azure/install-azure-cli
@@ -499,6 +273,7 @@ The original author of this project is [Simon Kurtz][simon-kurtz].
[infra-appgw-apim]: ./infrastructure/appgw-apim/
[infra-appgw-apim-pe]: ./infrastructure/appgw-apim-pe/
[infra-simple-apim]: ./infrastructure/simple-apim
+[openssf]: https://www.bestpractices.dev/projects/11057
[pytest-docs]: https://docs.pytest.org/
[pytest-docs-versioned]: https://docs.pytest.org/en/8.2.x/
[python]: https://www.python.org/
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
index 21370a0..fd37bf2 100644
--- a/TROUBLESHOOTING.md
+++ b/TROUBLESHOOTING.md
@@ -4,6 +4,7 @@ This guide helps you resolve common issues when working with the Azure API Manag
## Table of Contents
+- [Setup Issues](#setup-issues)
- [Deployment Errors](#deployment-errors)
- [Authentication Issues](#authentication-issues)
- [Notebook and Development Environment Issues](#notebook-and-development-environment-issues)
@@ -11,6 +12,24 @@ This guide helps you resolve common issues when working with the Azure API Manag
- [Resource Management Issues](#resource-management-issues)
- [Getting Additional Help](#getting-additional-help)
+## Setup Issues
+
+If you encounter import errors (e.g., `ModuleNotFoundError: No module named 'requests'` or cannot import shared modules), try these steps:
+
+1. **Fix Python path configuration**:
+ ```bash
+ python setup/local_setup.py --generate-env
+ ```
+
+2. **Verify setup**:
+ ```bash
+ python setup/verify_local_setup.py
+ ```
+
+3. **Restart VS Code** after running the above commands.
+
+4. **Check Python interpreter**: Use `Ctrl+Shift+P` โ "Python: Select Interpreter" and choose your `.venv` interpreter.
+
## Deployment Errors
### "The content for this response was already consumed"