Merge origin/main preferring incoming changes

Co-authored-by: paolosalvatori <1658419+paolosalvatori@users.noreply.github.com>

Author: Copilot

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @localstack/smurf

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+<!--
+Please refer to the contribution guidelines before raising a PR.
+https://github.com/localstack/localstack/blob/main/docs/CONTRIBUTING.md
+-->
+
+## Motivation
+
+<!--
+Elaborate the background and intent for raising this PR.
+-->
+
+## Changes
+
+<!--
+Summarise the changes proposed in the PR.
+-->
+
+## Tests
+
+<!--
+Optional: How are the proposed changes tested?
+-->
+
+## Related
+
+<!--
+Optional: Links to related issues and references (e.g., Linear IDs).
+-->

.github/scripts/build-matrix.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Builds a dynamic GitHub Actions matrix for run-samples.yml.
+# Usage: build-matrix.sh <run_mode> [base_sha]
+
+# "all" runs every test; "changed" only runs tests whose watch_folders have modified files
+RUN_MODE="${1:-all}"
+BASE_SHA="${2:-}"
+
+# Get JSON metadata for all tests from run-samples.sh --list
+TEST_META=$(./run-samples.sh --list)
+TOTAL=$(echo "$TEST_META" | jq length)
+echo "Run mode: $RUN_MODE | Total tests: $TOTAL"
+
+# Changes to these files affect all tests, so any modification triggers a full run
+INFRA_FILES="run-samples.sh Makefile .github/workflows/run-samples.yml .github/scripts/build-matrix.sh pyproject.toml requirements-dev.txt requirements-runtime.txt"
+
+if [[ "$RUN_MODE" == "changed" && -n "$BASE_SHA" ]]; then
+  # Get list of files changed between base branch and current HEAD
+  CHANGED=$(git diff --name-only "$BASE_SHA"..HEAD || true)
+  echo "Changed files:"
+  echo "$CHANGED"
+
+  # Safety net: if any infrastructure file changed, run all tests
+  RUN_ALL=false
+  for f in $INFRA_FILES; do
+    if echo "$CHANGED" | grep -qF "$f"; then
+      echo "Infra changed: $f -> running all"
+      RUN_ALL=true && break
+    fi
+  done
+
+  if [[ "$RUN_ALL" == "true" ]]; then
+    INDICES=$(seq 0 $((TOTAL-1)))
+  else
+    # Match changed files against each test's watch_folders using prefix matching
+    INDICES=""
+    for (( i=0; i<TOTAL; i++ )); do
+      mapfile -t folders < <(echo "$TEST_META" | jq -r ".[$i].watch_folders[]")
+      for wf in "${folders[@]}"; do
+        if echo "$CHANGED" | grep -q "^${wf}/"; then
+          INDICES+=" $i" && break
+        fi
+      done
+    done
+    INDICES=$(echo "$INDICES" | xargs)
+  fi
+else
+  # "all" mode: select every test
+  INDICES=$(seq 0 $((TOTAL-1)))
+fi
+
+# Output the matrix JSON for GitHub Actions
+if [[ -z "${INDICES:-}" ]]; then
+  echo "No tests to run."
+  echo "has_tests=false" >> "$GITHUB_OUTPUT"
+  echo 'matrix={"include":[]}' >> "$GITHUB_OUTPUT"
+else
+  echo "has_tests=true" >> "$GITHUB_OUTPUT"
+  # Convert space-separated indices to JSON array, then build the matrix object
+  IDX_JSON=$(echo "$INDICES" | tr ' ' '\n' | jq -R 'tonumber' | jq -s '.')
+  MATRIX=$(echo "$TEST_META" | jq -c --argjson idx "$IDX_JSON" \
+    '{include: [$idx[] as $i | .[$i] | {shard, splits, name}]}')
+  echo "matrix=$MATRIX" >> "$GITHUB_OUTPUT"
+  echo "Matrix:" && echo "$MATRIX" | jq .
+fi

.github/workflows/run-samples.yml

@@ -1,12 +1,7 @@
 name: Samples CI
 
-# Theory of Operation:
-# This workflow automates the testing of Azure sample applications against the LocalStack Azure emulator.
-# It follows the best practices from the localstack-pro repository:
-# 1. Parallel Testing: Splits the sample suite into shards to reduce execution time.
-# 2. Standardized Tooling: Uses a Makefile for environment setup and test orchestration.
-# 3. Cloud Emulation: Configures the Azure CLI to target the LocalStack emulator.
-# 4. IaC Coverage: Tests bash scripts, Terraform deployments, and Bicep deployments.
+# Tests Azure samples against the LocalStack emulator.
+# Each test runs in its own job. Set DEFAULT_RUN_MODE to 'changed' to only run affected tests.
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
@@ -16,18 +11,67 @@ on:
   pull_request:
     branches: [ main ]
   workflow_dispatch:
+    inputs:
+      run_mode:
+        description: "Test mode: 'all' runs every test, 'changed' runs only tests with modified files"
+        required: false
+        type: choice
+        options:
+          - all
+          - changed
+        default: changed
+
+# Default run mode for pull_request events (change to 'changed' to only run affected tests)
+env:
+  DEFAULT_RUN_MODE: changed
 
 jobs:
+  # Lightweight job that builds the dynamic test matrix for the main test jobs
+  setup:
+    name: "Build Test Matrix"
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.build-matrix.outputs.matrix }}
+      has_tests: ${{ steps.build-matrix.outputs.has_tests }}
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history needed for git diff in "changed" mode
+
+      - name: Build dynamic matrix
+        id: build-matrix
+        run: |
+          # Pick run mode: manual dispatch uses the dropdown, PRs use the env default
+          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+            RUN_MODE="${{ github.event.inputs.run_mode }}"
+          else
+            RUN_MODE="${{ env.DEFAULT_RUN_MODE }}"
+          fi
+
+          # In "changed" mode, determine the base commit to diff against
+          BASE_SHA=""
+          if [[ "$RUN_MODE" == "changed" ]]; then
+            if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+              BASE_SHA="${{ github.event.pull_request.base.sha }}"
+            else
+              BASE_SHA=$(git rev-parse origin/main 2>/dev/null || git rev-parse HEAD~1)
+            fi
+          fi
+
+          .github/scripts/build-matrix.sh "$RUN_MODE" "$BASE_SHA"
+
+  # Each test runs in its own job — one matrix entry per test from the setup job
   scripts:
-    name: "Run Test Scripts (amd64) — Part ${{ matrix.shard }} of ${{ matrix.splits }}"
+    name: "Test: ${{ matrix.name }}"
+    needs: setup
+    if: needs.setup.outputs.has_tests == 'true'  # Skip entirely when no tests match
     environment: AZURE
     strategy:
       fail-fast: false
-      matrix:
-        shard: [1, 2, 3, 4]
-        splits: [4]
-    runs-on: github-ubuntu2204-amd64-4
-    
+      matrix: ${{ fromJSON(needs.setup.outputs.matrix) }}
+    runs-on: ubuntu-22.04
+
     env:
       IMAGE_NAME: localstack/localstack-azure-alpha
       DEFAULT_TAG: latest
@@ -48,7 +92,12 @@ jobs:
       - name: Set up .NET
         uses: actions/setup-dotnet@v4
         with:
-          dotnet-version: '9.0'
+          dotnet-version: '10.0'
+
+      - uses: actions/setup-java@v5
+        with:
+          distribution: 'temurin'
+          java-version: '25'
 
       - name: Install System Dependencies
         # Essential tools for script execution, app packaging, and database connectivity.
@@ -67,7 +116,7 @@ jobs:
           terraform_wrapper: false
 
       - name: Install test dependencies
-        # Mirroring the localstack-pro approach: install all Python dependencies 
+        # Mirroring the localstack-pro approach: install all Python dependencies
         # (including the localstack CLI) into a virtual environment to avoid system-level conflicts.
         run: make install
 
@@ -80,24 +129,23 @@ jobs:
           password: ${{ secrets.DOCKERHUB_PULL_TOKEN }}
 
       - name: Free up disk space
-        # Azure emulator images are large. Pruning unused Docker objects ensures enough 
+        # Azure emulator images are large. Pruning unused Docker objects ensures enough
         # disk space is available on the GitHub runner for image pulls and sidecar containers.
         run: |
           docker system prune -af --volumes
           docker builder prune -af
 
       - name: Pull LocalStack Azure Image
-        # Explicitly pull the image before starting. This mirrors the "Build Docker Image" 
+        # Explicitly pull the image before starting. This mirrors the "Build Docker Image"
         # step in localstack-pro and ensures the pull logic is separated from the start logic.
         run: docker pull ${{ env.IMAGE_NAME }}:${{ env.DEFAULT_TAG }}
 
       - name: Start LocalStack
         # Run the emulator in detached mode using the virtual environment.
-        # We use 'python -m localstack.cli.main' to ensure the correct CLI version from the venv is used.
         run: |
           source .venv/bin/activate
-          python -m localstack.cli.main start -d
-          python -m localstack.cli.main wait -t 120
+          python -m localstack_cli.cli.main start -d
+          python -m localstack_cli.cli.main wait -t 120
         env:
           IMAGE_NAME: ${{ env.IMAGE_NAME }}:${{ env.DEFAULT_TAG }}
           LOCALSTACK_AUTH_TOKEN: ${{ secrets.TEST_LOCALSTACK_AUTH_TOKEN }}
@@ -109,21 +157,35 @@ jobs:
 
       - name: Install Azure Functions Core Tools
         # Required for publishing function app samples to the emulator.
-        run: npm install -g azure-functions-core-tools@4 --unsafe-perm true
+        run: |
+          MAX_RETRIES=3
+          DELAY=15
+          for i in $(seq 1 $MAX_RETRIES); do
+            echo "Attempt $i/$MAX_RETRIES..."
+            npm install -g azure-functions-core-tools@4 --unsafe-perm true && break
+            if [ "$i" -eq "$MAX_RETRIES" ]; then
+              echo "All $MAX_RETRIES attempts failed"
+              exit 1
+            fi
+            echo "Retrying in ${DELAY}s..."
+            sleep $DELAY
+            DELAY=$((DELAY * 2))
+          done
 
       - name: Install MSSQL ODBC and Tools
-        # Required for the 'web-app-sql-database' sample which uses 'sqlcmd' to 
+        # Required for the 'web-app-sql-database' sample which uses 'sqlcmd' to
         # initialize and verify the database schema in the local emulator.
         run: |
+          sudo rm -f /etc/apt/sources.list.d/microsoft-prod.list
           curl https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/microsoft.asc
           curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
           sudo apt-get update
           sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 mssql-tools18
           echo "/opt/mssql-tools18/bin" >> $GITHUB_PATH
 
-      - name: Run Test Scripts
-        # Executes the sharded test suite. Each shard runs a subset of samples in parallel.
-        # This includes bash scripts, Terraform deployments, and Bicep deployments.
+      - name: "Run: ${{ matrix.name }}"
+        # Each job runs exactly one test. SPLITS equals the total test count, and SHARD
+        # is the 1-based index of this specific test, so run-samples.sh executes only it.
         run: make test SHARD=${{ matrix.shard }} SPLITS=${{ matrix.splits }}
         env:
           LOCALSTACK_AUTH_TOKEN: ${{ secrets.TEST_LOCALSTACK_AUTH_TOKEN }}

.gitignore

@@ -22,6 +22,7 @@ bld/
 [Oo]bj/
 [Ll]og/
 [Ll]ogs/
+publish/
 
 # .NET Core
 project.lock.json
@@ -216,4 +217,13 @@ cython_debug/
 #  before adapting.
 #  Usually, these files will be generated by your IDE, so it is
 #  better to have them ignored.
-.idea/
+.idea/
+## Terraform
+.terraform/
+*.tfstate
+*.tfstate.backup
+tfplan
+override.tf
+override.tf.json
+*_override.tf
+*_override.tf.json

README.md

@@ -28,12 +28,15 @@ This repository contains comprehensive sample projects demonstrating how to deve
 |-------------|-------------|
 | [Function App and Storage](./samples/function-app-storage-http/dotnet/README.md) | Azure Functions App using Blob, Queue, and Table Storage |
 | [Function App and Front Door](./samples/function-app-front-door/python/README.md) | Azure Functions App exposed via Front Door |
-| [Function App and Managed Identities](./samples/function-app-managed-identity/python/README.md) | Azure Function App using Managed Identities | 
-| [Web App and PostgreSQL Database](./samples/web-app-postgresql-database/python/README.md) | Azure Web App using PostgreSQL Flexible Server |
+| [Function App and Managed Identities](./samples/function-app-managed-identity/python/README.md) | Azure Function App using Managed Identities |
+| [Function App and Service Bus](./samples/function-app-service-bus/dotnet/README.md) | Azure Function App using Service Bus |
 | [Web App and CosmosDB for MongoDB API ](./samples/web-app-cosmosdb-mongodb-api/python/README.md) | Azure Web App using CosmosDB for MongoDB API |
-| [Web App and CosmosDB for NoSQL API ](./samples/web-app-cosmosdb-nosql-api/python/README.md) | Azure Web App using CosmosDB for NoSQL API | 
-| [Web App and Managed Identities](./samples/web-app-managed-identity/python/README.md) | Azure Web App using Managed Identities | 
-| [Web App and SQL Database ](./samples/web-app-sql-database/python/README.md) | Azure Web App using SQL Database | 
+| [Web App and CosmosDB for NoSQL API ](./samples/web-app-cosmosdb-nosql-api/python/README.md) | Azure Web App using CosmosDB for NoSQL API |
+| [Web App and Managed Identities](./samples/web-app-managed-identity/python/README.md) | Azure Web App using Managed Identities |
+| [Web App and SQL Database ](./samples/web-app-sql-database/python/README.md) | Azure Web App using SQL Database |
+| [Web App with Custom Docker Image](./samples/web-app-custom-image/python/README.md) | Azure Web App running a custom Docker image |
+| [ACI and Blob Storage](./samples/aci-blob-storage/python/README.md) | Azure Container Instances with ACR, Key Vault, and Blob Storage |
+| [Azure Service Bus with Spring Boot](./samples/servicebus/java/README.md) | Azure Service Bus used by a Spring Boot application |
 
 ## Sample Structure
 
@@ -73,7 +76,7 @@ Follow the comprehensive setup guide in [LocalStack for Azure Quick Start](./doc
 
 ## Documentation
 
-- [LocalStack for Azure Documentation](https://azure.localstack.cloud/)
+- [LocalStack for Azure Documentation](https://docs.localstack.cloud/azure/)
 - [Azure CLI with LocalStack](https://azure.localstack.cloud/user-guides/sdks/az/)
 - [Supported Azure Services](https://azure.localstack.cloud/references/coverage/)
 

docs/LOCALSTACK.md

@@ -28,8 +28,15 @@ You can start the Azure emulator using one of the following methods:
 Make sure the `localstack` CLI is installed (`pip install localstack` or `brew install localstack/tap/localstack`).
 
 ```bash
+# Set the authentication token
 export LOCALSTACK_AUTH_TOKEN=<your_auth_token>
-IMAGE_NAME=localstack/localstack-azure-alpha localstack start
+
+# Start the LocalStack Azure emulator
+IMAGE_NAME=localstack/localstack-azure-alpha localstack start -d
+localstack wait -t 60
+
+# Route all Azure CLI calls to the LocalStack Azure emulator
+azlocal start-interception
 ```
 
 This: