diff --git a/plugin/skills/azure-cloud-migrate/SKILL.md b/plugin/skills/azure-cloud-migrate/SKILL.md new file mode 100644 index 00000000..48d02b76 --- /dev/null +++ b/plugin/skills/azure-cloud-migrate/SKILL.md @@ -0,0 +1,39 @@ +--- +name: azure-cloud-migrate +description: "Assess and migrate cross-cloud workloads to Azure. Generates assessment reports and converts code from AWS, GCP, or other providers to Azure services. WHEN: \"migrate Lambda to Azure Functions\", \"migrate AWS to Azure\", \"Lambda migration assessment\", \"convert s AWS erverless to Azure\", \"migration readiness report\", \"migrate from AWS\", \"migrate from GCP\", \"cross-cloud migration\"." +--- + +# Azure Cloud Migrate + +> This skill handles **assessment and code migration** of existing cloud workloads to Azure. + +## Rules + +1. Follow phases sequentially — do not skip +2. Generate assessment before any code migration +3. Load the scenario reference and follow its rules +4. Use `mcp_azure_mcp_get_bestpractices` and `mcp_azure_mcp_documentation` MCP tools +5. Use the latest supported runtime for the target service +6. Destructive actions require `ask_user` — [global-rules](references/services/functions/global-rules.md) + +## Migration Scenarios + +| Source | Target | Reference | +|--------|--------|-----------| +| AWS Lambda | Azure Functions | [lambda-to-functions.md](references/services/functions/lambda-to-functions.md) | + +> No matching scenario? Use `mcp_azure_mcp_documentation` and `mcp_azure_mcp_get_bestpractices` tools. + +## Output Directory + +All output goes to `-azure/` at workspace root. Never modify the source directory. + +## Steps + +1. **Create** `-azure/` at workspace root +2. **Assess** — Analyze source, map services, generate report → [assessment.md](references/services/functions/assessment.md) +3. **Migrate** — Convert code using target programming model → [code-migration.md](references/services/functions/code-migration.md) +4. **Ask User** — "Migration complete. Test locally or deploy to Azure?" +5. **Hand off** to azure-prepare for infrastructure, testing, and deployment + +Track progress in `migration-status.md` — see [workflow-details.md](references/workflow-details.md). diff --git a/plugin/skills/azure-cloud-migrate/references/services/functions/assessment.md b/plugin/skills/azure-cloud-migrate/references/services/functions/assessment.md new file mode 100644 index 00000000..8b1e5dbf --- /dev/null +++ b/plugin/skills/azure-cloud-migrate/references/services/functions/assessment.md @@ -0,0 +1,154 @@ +# Assessment Phase + +Generate a migration assessment report before any code changes. + +## Prerequisites + +- Workspace contains AWS Lambda functions, SAM templates, or CloudFormation templates +- Prompt user to upload relevant files if not present + +## Assessment Steps + +1. **Identify Functions** — List all Lambda functions with runtimes, triggers, and dependencies +2. **Map AWS Services** — Map AWS services to Azure equivalents (see [lambda-to-functions.md](lambda-to-functions.md)) +3. **Map Properties** — Map Lambda properties to Azure Functions properties +4. **Check Dependencies** — List 3rd-party libraries and verify Azure compatibility +5. **Analyze Code** — Check language support and runtime differences +6. **Map Triggers** — Identify equivalent Azure Functions triggers +7. **Map Deployment** — Identify equivalent Azure deployment strategies (CLI, Bicep, azd) +8. **Review CI/CD** — Check pipeline compatibility with Azure DevOps or GitHub Actions +9. **Map Monitoring** — Map CloudWatch → Application Insights / Azure Monitor + +## Code Preview + +During assessment, show a **sneak peek** of what the migrated Azure Functions code will look like for each function. Use bindings and triggers (not SDKs) in all previews, following Azure Functions best practices. **Always use the newest generally available (GA) language runtime listed in the Azure Functions supported languages documentation** in previews (for example, the latest Node.js LTS or newest Python GA version). This helps the user understand the migration scope before committing to code migration. + +> ⚠️ **Binding-first rule**: Code previews MUST use `input.storageBlob()`, `output.storageBlob()`, `app.storageQueue()`, etc. instead of `BlobServiceClient`, `QueueClient`, or other SDK clients. Only use SDK for services that have no binding equivalent. + +## Architecture Diagrams + +Generate two diagrams: +1. **Current State** — AWS Lambda architecture with triggers and integrations +2. **Target State** — Azure Functions architecture showing equivalent structure + +## Assessment Report Format + +> ⚠️ **MANDATORY**: Use these exact section headings in every assessment report. Do NOT rename, reorder, or omit sections. + +The report MUST be saved as `migration-assessment-report.md` inside the output directory (`-azure/`). + +```markdown +# Migration Assessment Report + +## 1. Executive Summary + +| Property | Value | +|----------|-------| +| **Total Functions** | | +| **Source Platform** | AWS Lambda | +| **Source Runtime** | | +| **Target Platform** | Azure Functions | +| **Target Runtime** | | +| **Migration Readiness** | | +| **Estimated Effort** | | +| **Assessment Date** | | + +## 2. Functions Inventory + +| # | Function Name | Runtime | Trigger Type | Memory (MB) | Timeout (s) | Description | +|---|--------------|---------|-------------- |-------------|-------------|-------------| +| 1 | | | | | | | + +## 3. Service Mapping + +| AWS Service | Azure Equivalent | Migration Complexity | Notes | +|-------------|------------------|----------------------|-------| +| Lambda | Azure Functions | | | +| API Gateway | Azure Functions HTTP Trigger / APIM | | | +| S3 | Azure Blob Storage | | | +| DynamoDB | Cosmos DB | | | +| SQS | Service Bus / Storage Queue | | | +| SNS | Event Grid | | | +| CloudWatch | Application Insights / Azure Monitor | | | +| IAM Roles | Managed Identity + RBAC | | | +| CloudFormation / SAM | Bicep / ARM Templates | | | + +## 4. Trigger & Binding Mapping + +| # | Function Name | AWS Trigger | Azure Trigger | AWS Inputs/Outputs | Azure Bindings | Notes | +|---|--------------|-------------|---------------|--------------------| ---------------|-------| +| 1 | | | | | | | + +## 5. Dependencies Analysis + +| # | Package/Library | Version | AWS-Specific? | Azure Equivalent | Compatible? | Notes | +|---|----------------|---------|---------------|------------------|-------------|-------| +| 1 | | | | | | | + +## 6. Environment Variables & Configuration + +| # | AWS Variable | Purpose | Azure Equivalent | Auth Method | Notes | +|---|-------------|---------|------------------|-------------|-------| +| 1 | | | | Managed Identity / App Setting | | + +## 7. Architecture Diagrams + +### 7a. Current State (AWS) + + + +### 7b. Target State (Azure) + + + +## 8. IAM & Security Mapping + +| AWS IAM Role/Policy | Azure RBAC Role | Scope | Notes | +|---------------------|-----------------|-------|-------| +| | | | | + +## 9. Monitoring & Observability Mapping + +| AWS Service | Azure Equivalent | Migration Notes | +|-------------|------------------|-----------------| +| CloudWatch Logs | Application Insights | | +| CloudWatch Metrics | Azure Monitor Metrics | | +| CloudWatch Alarms | Azure Monitor Alerts | | +| X-Ray | Application Insights (distributed tracing) | | + +## 10. CI/CD & Deployment Mapping + +| AWS Tool | Azure Equivalent | Notes | +|----------|------------------|-------| +| SAM CLI | Azure Functions Core Tools / azd | | +| CloudFormation | Bicep / ARM Templates | | +| CodePipeline | Azure DevOps Pipelines / GitHub Actions | | +| CodeBuild | Azure DevOps Build / GitHub Actions | | + +## 11. Project Structure Comparison + +| AWS Lambda Structure | Azure Functions Structure | +|---------------------|--------------------------| +| `template.yaml` (SAM) | `host.json` | +| `handler.js / handler.py` | `src/app.js` / `src/function_app.py` | +| `requirements.txt` / `package.json` | `requirements.txt` / `package.json` | +| Per-function directories (optional) | Single entry point (v4 JS / v2 Python) | +| `event` object | Trigger-specific parameter | +| `context` object | `InvocationContext` | + +## 12. Recommendations + +1. **Runtime**: +2. **Hosting Plan**: +3. **IaC Strategy**: +4. **Auth Strategy**: +5. **Monitoring**: + +## 13. Next Steps + +- [ ] Review and approve this assessment report +- [ ] Proceed to code migration (azure-cloud-migrate Phase 2) +- [ ] Hand off to azure-prepare for IaC generation +``` + +> 💡 **Tip:** Use `mcp_azure_mcp_get_bestpractices` tool to learn Azure Functions project structure best practices for the comparison. diff --git a/plugin/skills/azure-cloud-migrate/references/services/functions/code-migration.md b/plugin/skills/azure-cloud-migrate/references/services/functions/code-migration.md new file mode 100644 index 00000000..8cab61f9 --- /dev/null +++ b/plugin/skills/azure-cloud-migrate/references/services/functions/code-migration.md @@ -0,0 +1,138 @@ +# Code Migration Phase + +Migrate AWS Lambda function code to Azure Functions. + +## Prerequisites + +- Assessment report completed +- Azure Functions extension installed in VS Code +- Best practices loaded via `mcp_azure_mcp_get_bestpractices` tool + +## Rules + +- If runtime is Python or Node.js: **do NOT create function.json files** +- If runtime is .NET (in-process or isolated) or Java: **do NOT hand-author function.json** — bindings metadata is generated from attributes/annotations at build time +- Use extension bundle version `[4.*, 5.0.0)` in host.json +- Use latest programming model (v4 for JavaScript, v2 for Python) +- **Always use bindings and triggers instead of SDKs** — For blob read/write, use `input.storageBlob()` / `output.storageBlob()` with `extraInputs`/`extraOutputs`. For queues, use `app.storageQueue()` or `app.serviceBusQueue()`. Only use SDK when there is no equivalent binding (e.g., Azure AI, custom HTTP calls) +- **Always use the latest supported language runtime** — Consult [supported languages](https://learn.microsoft.com/en-us/azure/azure-functions/supported-languages) and select the newest GA version. Do NOT default to an older LTS version when a newer version is available on Azure Functions. + +## Steps + +1. **Install Azure Functions Extension** — Ensure VS Code extension is installed +2. **Load Best Practices** — Use `mcp_azure_mcp_get_bestpractices` tool for code generation guidance +3. **Create Project Structure** — Set up the Azure Functions project inside the output directory (`-azure/`). Do NOT create files inside the original AWS directory +4. **Migrate Functions** — Convert each Lambda function to Azure Functions equivalent +5. **Update Dependencies** — Replace AWS SDKs with Azure SDKs in package.json / requirements.txt +6. **Configure Bindings** — Set up triggers and bindings inline (v4 JS / v2 Python) +7. **Configure Environment** — Map Lambda env vars to Azure Functions app settings +8. **Add Error Handling** — Ensure proper error handling in all functions + +## Key Configuration Files + +### host.json + +```json +{ + "version": "2.0", + "extensionBundle": { + "id": "Microsoft.Azure.Functions.ExtensionBundle", + "version": "[4.*, 5.0.0)" + }, + "extensions": { + "queues": { + "maxPollingInterval": "00:00:02", + "visibilityTimeout": "00:00:30", + "batchSize": 1, + "maxDequeueCount": 5 + } + }, + "logging": { + "applicationInsights": { + "samplingSettings": { + "isEnabled": true, + "excludedTypes": "Request" + } + } + } +} +``` + +## Critical Infrastructure Dependencies + +### Blob Trigger with EventGrid Source — Additional Requirements + +When migrating S3 event triggers to Azure blob triggers with `source: 'EventGrid'`, the following infrastructure must be configured **at the IaC level** (not code level). Failure to set these up results in silent trigger failures. + +| Requirement | Why | Consequence of Missing | +|------------|-----|----------------------| +| **Queue endpoint** (`AzureWebJobsStorage__queueServiceUri`) | Blob extension uses queues internally for poison-message tracking with EventGrid source | Function fails to index: "Unable to find matching constructor...QueueServiceClient" | +| **Always-ready instances** (Flex Consumption only) | Blob trigger group must be running to register the Event Grid webhook | Trigger group never starts → webhook never registered → events never delivered | +| **Event Grid subscription via Bicep/ARM** | CLI-based webhook validation handshake times out on Flex Consumption | Use `listKeys()` in Bicep to obtain the `blobs_extension` system key at deployment time | +| **Storage Queue Data Contributor** RBAC | Identity-based queue access for poison messages | 403 errors during blob trigger indexing | + +See [lambda-to-functions.md](lambda-to-functions.md#flex-consumption--blob-trigger-with-eventgrid-source) for Bicep patterns. + +### UAMI Credential Pattern + +When using User Assigned Managed Identity (UAMI), `DefaultAzureCredential()` without arguments tries System Assigned first and fails. Always pass the client ID: + +```javascript +const credential = new DefaultAzureCredential({ + managedIdentityClientId: process.env.AZURE_CLIENT_ID +}); +``` + +Add `AZURE_CLIENT_ID` as an app setting in Bicep pointing to the UAMI client ID. + +### azd init Workaround for Non-Empty Directories + +`azd init --template