Skip to content

Local Development Guide

This guide covers setting up and running the IPAM Function App locally for development and testing.

Prerequisites

  • PowerShell 7.4+: Required for Azure Functions PowerShell worker
  • Azure Functions Core Tools: Install via npm install -g azure-functions-core-tools@4
  • Azurite: Azure Storage emulator for local Table Storage
  • Install: npm install -g azurite
  • Azure PowerShell Modules: Az.Accounts, Az.ResourceGraph (baked into deployment package via Save-Module during build)

Quick Start

1. Start Azurite

Azurite provides local emulation of Azure Table Storage. Start it using the provided script:

.\scripts\Start-Azurite.ps1

Or start it manually:

azurite --location .\__azurite_data__ --tablePort 10002 --blobPort 10000 --queuePort 10001 --silent

Note: Azurite must be running before starting the Function App.

2. Seed Test Data (Optional)

To populate Azurite with test data for development:

.\scripts\Seed-TestData.ps1

This creates sample networks in multiple partitions for testing.

3. Start Azure Functions

Start the Function App locally:

func start

Or use the VS Code launch configuration: Azure Functions: Start (F5)

The functions will be available at:

  • Vendor (getNewNetwork): http://localhost:7071/api/getNewNetwork
  • Manager: Timer trigger (runs on schedule defined in MANAGER_TIMER_SCHEDULE)

Configuration

Local Settings

The local.settings.json file contains local development configuration:

  • AzureWebJobsStorage: Set to UseDevelopmentStorage=true for Azurite
  • StorageEndpoint: Azurite Table Storage endpoint (http://127.0.0.1:10002)

Required App Settings

For local testing, ensure these are set in local.settings.json:

  • SUPERNETS_CONFIG: JSON array defining subscription/region/supernet scopes
  • SCOPE_CONFIG_MANIFEST: JSON defining allocation manifest
  • CIDR_SIZE_MIN, CIDR_SIZE_MAX, CIDR_SIZE_DEFAULT: CIDR size validation
  • LEASE_DURATION_HOURS: Lease expiration duration

See docs/Configuration.md for detailed configuration documentation.

Development Workflow

Testing Vendor Function

  1. Ensure Azurite is running
  2. Seed test data (optional): .\scripts\Seed-TestData.ps1
  3. Start Function App: func start
  4. Test allocation:
$body = @{
  SessionId = 'test-session-123'
  CidrSize  = 22
} | ConvertTo-Json

Invoke-RestMethod -Uri 'http://localhost:7071/api/getNewNetwork' -Method Post -Body $body -ContentType 'application/json'

Testing Manager Function

  1. Ensure Azurite is running
  2. Load ARG fixtures or mock ARG responses
  3. Manually trigger Manager function or wait for timer schedule
  4. Verify Table Storage is updated with gaps

Testing

For comprehensive testing documentation, see docs/Testing.md.

Local Testing Requirements

When running tests locally (vs. CI):

  • Azurite must be running: Start it with .\scripts\Start-Azurite.ps1 before running tests
  • Tests use local Function App: Tests automatically start/stop func start via FunctionTestHarness.psm1
  • Table Storage uses Azurite: Tests connect to http://127.0.0.1:10002 instead of Azure Storage
  • No Azure authentication required: Local tests use Azurite emulation, not real Azure resources

To run tests:

# Ensure Azurite is running first
.\scripts\Start-Azurite.ps1

# Run all tests
Invoke-Pester

# Run specific test file
Invoke-Pester -Path Tests\GetNewNetwork.Tests.ps1

Debugging

VS Code Debugging

  1. Set breakpoints in function code
  2. Use launch configuration: Attach to PowerShell Functions
  3. Start Function App: func start
  4. Attach debugger when functions are loaded

Logging

Functions use structured logging via the Logging.psm1 module. Logs appear in:

  • Console output when running func start
  • Application Insights (when configured in Azure)

Table Storage Inspection

Inspect Azurite Table Storage data:

$client = Get-TableStorageClient -ConnectionString 'UseDevelopmentStorage=true' -TableName 'networkCidr'
$entities = Get-TableEntities -Client $client -PartitionKey 'test-partition'
$entities | Format-Table

Troubleshooting

Azurite Not Starting

  • Ensure port 10002 (Table), 10000 (Blob), 10001 (Queue) are not in use
  • Check if Azurite is already running: Get-Process azurite -ErrorAction SilentlyContinue
  • Verify Azurite is installed: azurite --version

Functions Not Starting

  • Verify PowerShell 7.4+ is installed: $PSVersionTable.PSVersion
  • Check that modules are baked into the deployment package (modules are not managed via requirements.psd1)
  • Ensure local.settings.json is valid JSON

Table Storage Connection Errors

  • Verify Azurite is running on port 10002
  • Check AzureWebJobsStorage in local.settings.json is set to UseDevelopmentStorage=true
  • Ensure StorageEndpoint points to http://127.0.0.1:10002

Module Import Errors

  • Modules are loaded from modules/ directory relative to function files
  • Verify module paths are correct in function run.ps1 files
  • Check module exports match function usage

Other Resources

  • See docs/Testing.md for detailed testing guide and patterns
  • See docs/Configuration.md for all configuration options
  • See docs/Authentication.md for Azure authentication requirements
  • See Architecture.md for system design details