@microsoft/terraform-cdk-constructs 1.0.0 → 1.2.0

package/README.md

@@ -20,18 +20,48 @@ With AZAPI L2 Constructs, you get the following benefits:
 - **Version Flexibility**: Choose specific API versions for your resources
 - **Rapid Feature Adoption**: Access new Azure features immediately without waiting for provider updates
 - **Enhanced Abstraction**: Higher-level abstractions over Azure resources with type safety
+- **Built-in Monitoring**: One-line setup for comprehensive monitoring with customizable alerts and diagnostic settings
+- **Schema Validation**: Automatic validation of properties against Azure API schemas
 - **Reusability**: Encapsulate common patterns and best practices in your infrastructure code
+- **Testing Utilities**: Helper functions for integration tests including naming conventions, metadata, and resource cleanup
 - **Direct IDE Integration**: Access detailed documentation directly within your IDE
 - **Zero Provider Setup**: AZAPI provider bindings included in the package
 
 ## Currently Supported Services
 
+### Compute
+
+| Service | API Versions | Monitoring Support | Status |
+|---------|-------------|-------------------|--------|
+| [Virtual Machines](./src/azure-virtualmachine/README.md) | 2024-07-01, 2024-11-01, 2025-04-01 | ✅ Built-in | ✅ Available |
+| [AKS Clusters](./src/azure-aks/README.md) | 2025-05-01, 2025-07-01, 2025-08-01 | ✅ Built-in | ✅ Available |
+| [Virtual Machine Scale Sets](./src/azure-vmss/README.md) | 2025-01-02, 2025-02-01, 2025-04-01 | ✅ Built-in | ✅ Available |
+
+### Networking
+
+| Service | API Versions | Status |
+|---------|-------------|--------|
+| [Virtual Networks](./src/azure-virtualnetwork/README.md) | 2024-07-01, 2024-10-01, 2025-01-01 | ✅ Available |
+| [Subnets](./src/azure-subnet/README.md) | 2024-07-01, 2024-10-01, 2025-01-01 | ✅ Available |
+| [Network Interfaces](./src/azure-networkinterface/README.md) | 2024-07-01, 2024-10-01, 2025-01-01 | ✅ Available |
+| [Network Security Groups](./src/azure-networksecuritygroup/README.md) | 2024-07-01, 2024-10-01, 2025-01-01 | ✅ Available |
+| [Public IP Addresses](./src/azure-publicipaddress/README.md) | 2024-07-01, 2024-10-01, 2025-01-01 | ✅ Available |
+
+### Monitoring & Alerting
+
 | Service | API Versions | Status |
 |---------|-------------|--------|
-| Resource Groups | 2024-11-01, 2025-01-01, 2025-03-01 | ✅ Available |
-| Storage Accounts | 2023-01-01, 2023-05-01, 2024-01-01 | ✅ Available |
+| [Action Groups](./src/azure-actiongroup/README.md) | 2021-09-01 | ✅ Available |
+| [Metric Alerts](./src/azure-metricalert/README.md) | 2018-03-01 | ✅ Available |
+| [Activity Log Alerts](./src/azure-activitylogalert/README.md) | 2020-10-01 | ✅ Available |
+| [Diagnostic Settings](./src/azure-diagnosticsettings/README.md) | 2016-09-01, 2021-05-01-preview | ✅ Available |
+
+### Foundation
 
-*More services will be added in future releases using the same AZAPI architecture.*
+| Service | API Versions | Status |
+|---------|-------------|--------|
+| [Resource Groups](./src/azure-resourcegroup/README.md) | 2024-11-01, 2025-01-01, 2025-03-01 | ✅ Available |
+| [Storage Accounts](./src/azure-storageaccount/README.md) | 2023-01-01, 2023-05-01, 2024-01-01 | ✅ Available |
 
 ## Quick Example
 
@@ -98,45 +128,50 @@ npm install @microsoft/terraform-cdk-constructs
 
 That's it! The AZAPI provider classes are included in the package, so you don't need to configure additional providers or generate bindings.
 
-### Basic Usage Example
+## Built-in Monitoring & Alerting
+
+Azure L2 Constructs include comprehensive monitoring capabilities that can be enabled with a single method call. The monitoring framework automatically creates metric alerts, diagnostic settings, and activity log alerts for supported resources.
+
+### Quick Example
 
 ```typescript
-import * as azcdk from "@microsoft/terraform-cdk-constructs";
-import { Construct } from 'constructs';
-import { App, TerraformStack } from 'cdktf';
+import { VirtualMachine } from "@microsoft/terraform-cdk-constructs/azure-virtualmachine";
+import { ActionGroup } from "@microsoft/terraform-cdk-constructs/azure-actiongroup";
+
+// Enable monitoring with one line
+const vm = new VirtualMachine(this, "vm", {
+  name: "my-vm",
+  // ... VM configuration ...
+  monitoring: VirtualMachine.defaultMonitoring(actionGroup.id, workspaceId),
+});
+```
 
-class MyAzureInfra extends TerraformStack {
-  constructor(scope: Construct, name: string) {
-    super(scope, name);
+### Supported Resources
 
-    // Create a resource group
-    const rg = new azcdk.azure_resourcegroup.ResourceGroup(this, "main-rg", {
-      name: "rg-myproject-prod",
-      location: "eastus",
-      tags: {
-        environment: "production",
-        project: "myproject"
-      }
-    });
+| Resource | Monitoring Documentation |
+|----------|-------------------------|
+| Virtual Machines | [VM Monitoring Guide](./src/azure-virtualmachine/README.md#monitoring) |
+| AKS Clusters | [AKS Monitoring Guide](./src/azure-aks/README.md#monitoring) |
+| Virtual Machine Scale Sets | [VMSS Monitoring Guide](./src/azure-vmss/README.md#monitoring) |
+| Storage Accounts | [Storage Monitoring Guide](./src/azure-storageaccount/README.md#monitoring) |
 
-    // Create a storage account
-    const storage = new azcdk.azure_storageaccount.StorageAccount(this, "storage", {
-      name: "mystorageaccount",
-      location: "eastus",
-      resourceGroupId: rg.id,
-      sku: { name: "Standard_LRS" },
-      tags: {
-        environment: "production",
-        project: "myproject"
-      }
-    });
-  }
-}
+See the [Monitoring Guide](./docs/monitoring-guide.md) for comprehensive documentation on monitoring capabilities, customization options, and best practices.
 
-const app = new App();
-new MyAzureInfra(app, 'azure-infra');
-app.synth();
-```
+## Networking Constructs
+
+Build complete Azure networking infrastructure with type-safe constructs that provide automatic validation and version management.
+
+### Available Components
+
+| Component | Documentation |
+|-----------|--------------|
+| [Virtual Networks](./src/azure-virtualnetwork/README.md) | Define address spaces and network isolation with custom DNS and DDoS protection |
+| [Subnets](./src/azure-subnet/README.md) | Segment networks with service endpoints, delegations, and NSG association |
+| [Network Interfaces](./src/azure-networkinterface/README.md) | Attach to VMs with static/dynamic IPs and accelerated networking |
+| [Network Security Groups](./src/azure-networksecuritygroup/README.md) | Control traffic with inbound/outbound security rules |
+| [Public IP Addresses](./src/azure-publicipaddress/README.md) | Expose resources with static/dynamic allocation |
+
+See individual service documentation for detailed configuration examples and best practices.
 
 ## Version-Specific Usage
 
@@ -209,6 +244,7 @@ We welcome contributions to this project! See our documentation on [how to get s
 ## Documentation
 
 - [Architecture Documentation](./docs/ARCHITECTURE.md) - High-level architecture and design patterns
+- [Monitoring Guide](./docs/monitoring-guide.md) - Comprehensive monitoring and alerting documentation
 - [Versioning and Migrations User Guide](./docs/versioning-and-migrations-user-guide.md) - API version management and migration guidance
 - [Testing Guide](./docs/testing.md) - Testing practices and utilities
 - [Design Guide](./docs/design_guide.md) - Module design guidelines

package/docs/monitoring-guide.md

@@ -0,0 +1,206 @@
+# Monitoring & Alerting Guide
+
+Azure L2 Constructs include comprehensive monitoring capabilities that can be enabled with a single method call. The monitoring framework automatically creates metric alerts, diagnostic settings, and activity log alerts for supported resources.
+
+## Overview
+
+Monitoring is built directly into the constructs, allowing you to enable production-ready observability with minimal configuration. Each supported resource type includes sensible defaults for critical metrics while remaining fully customizable.
+
+## Supported Resources
+
+| Resource | Metric Alerts | Diagnostic Settings | Activity Log Alerts | Documentation |
+|----------|--------------|---------------------|-------------------|---------------|
+| Virtual Machines | CPU, Memory, Disk Queue | ✅ Yes | VM Deletion | [VM Monitoring](../src/azure-virtualmachine/README.md#monitoring) |
+| AKS Clusters | Node CPU/Memory, Failed Pods | ✅ Yes | Cluster Deletion | [AKS Monitoring](../src/azure-aks/README.md#monitoring) |
+| Virtual Machine Scale Sets | CPU, Memory, Disk Queue | ✅ Yes | VMSS Deletion | [VMSS Monitoring](../src/azure-vmss/README.md#monitoring) |
+| Storage Accounts | Availability, Egress, Transactions | ✅ Yes | Account Deletion | [Storage Monitoring](../src/azure-storageaccount/README.md#monitoring) |
+
+## Quick Start
+
+All monitoring-enabled resources follow the same pattern using the `defaultMonitoring()` static method:
+
+```typescript
+import { VirtualMachine } from "@microsoft/terraform-cdk-constructs/azure-virtualmachine";
+import { ActionGroup } from "@microsoft/terraform-cdk-constructs/azure-actiongroup";
+
+// Create action group for alert notifications
+const actionGroup = new ActionGroup(this, "alerts", {
+  name: "ops-alerts",
+  groupShortName: "OpsTeam",
+  resourceGroupId: resourceGroup.id,
+  emailReceivers: [{
+    name: "ops-email",
+    emailAddress: "ops@company.com",
+    useCommonAlertSchema: true,
+  }],
+});
+
+// Create resource with built-in monitoring
+const vm = new VirtualMachine(this, "vm", {
+  name: "my-vm",
+  location: "eastus",
+  resourceGroupId: resourceGroup.id,
+  // ... other VM configuration ...
+  
+  // Enable monitoring with one line
+  monitoring: VirtualMachine.defaultMonitoring(
+    actionGroup.id,
+    workspaceId  // Log Analytics workspace ID
+  ),
+});
+```
+
+## What Gets Created
+
+When you enable default monitoring, the following resources are automatically created:
+
+### 1. Metric Alerts
+
+Resource-specific metric alerts with sensible thresholds (e.g., CPU > 80%, Memory < 1GB). Each alert is configured with:
+- Appropriate severity levels
+- Evaluation frequency and window size
+- Aggregation methods
+- Actions linked to your action group
+
+### 2. Diagnostic Settings
+
+Sends all logs and metrics to Log Analytics workspace for:
+- Centralized monitoring and analysis
+- Long-term retention
+- Query and visualization capabilities
+- Integration with Azure Monitor
+
+### 3. Activity Log Alerts
+
+Tracks critical administrative operations such as:
+- Resource deletion events
+- Configuration changes
+- Security-related operations
+
+## Customization
+
+All monitoring configurations support customization through options:
+
+```typescript
+monitoring: VirtualMachine.defaultMonitoring(
+  actionGroup.id,
+  workspaceId,
+  {
+    // Customize thresholds
+    cpuThreshold: 90,              // Raise CPU alert threshold to 90%
+    memoryThreshold: 524288000,    // Lower memory threshold to 500MB
+    
+    // Adjust severities (0=Critical, 1=Error, 2=Warning, 3=Info, 4=Verbose)
+    cpuAlertSeverity: 1,           // Make CPU alerts critical
+    
+    // Enable/disable specific alerts
+    enableDiskQueueAlert: false,   // Disable disk queue monitoring
+    enableDeletionAlert: true,     // Keep deletion tracking
+  }
+)
+```
+
+## Service-Specific Documentation
+
+For detailed monitoring configuration options, examples, and available metrics, see the service-specific documentation:
+
+- **[Virtual Machine Monitoring](../src/azure-virtualmachine/README.md#monitoring)** - CPU, memory, disk, and network monitoring
+- **[AKS Cluster Monitoring](../src/azure-aks/README.md#monitoring)** - Node health, pod failures, and cluster metrics
+- **[VM Scale Set Monitoring](../src/azure-vmss/README.md#monitoring)** - Instance-level and aggregate monitoring
+- **[Storage Account Monitoring](../src/azure-storageaccount/README.md#monitoring)** - Availability, performance, and transaction tracking
+
+## Advanced Usage
+
+### Combining Default Monitoring with Custom Alerts
+
+You can extend the default monitoring configuration with additional custom alerts:
+
+```typescript
+const monitoring = VirtualMachine.defaultMonitoring(
+  actionGroup.id,
+  workspaceId
+);
+
+// Add a custom network traffic alert
+monitoring.metricAlerts?.push({
+  name: 'high-network-traffic',
+  description: 'Alert when network egress exceeds 10GB',
+  severity: 2,
+  frequency: 'PT5M',
+  windowSize: 'PT15M',
+  criteria: {
+    singleResourceMultipleMetricCriteria: [{
+      metricNamespace: 'Microsoft.Compute/virtualMachines',
+      metricName: 'Network Out Total',
+      aggregation: 'Total',
+      operator: 'GreaterThan',
+      threshold: 10737418240, // 10GB
+    }]
+  },
+  actionGroupIds: [actionGroup.id]
+});
+```
+
+### Fully Custom Monitoring
+
+For complete control, provide a custom monitoring configuration object. See individual service documentation for the complete monitoring configuration schema.
+
+## Best Practices
+
+1. **Always enable monitoring for production resources** - Use `defaultMonitoring()` as a baseline
+2. **Use Log Analytics workspaces** - Enable centralized logging and analysis
+3. **Configure action groups appropriately** - Ensure alerts reach the right teams
+4. **Customize thresholds for your workload** - Default values may not fit all scenarios
+5. **Test alerting** - Verify alerts trigger correctly before production deployment
+6. **Review metrics regularly** - Adjust thresholds based on actual usage patterns
+7. **Use multiple action groups** - Route different severity alerts to different teams
+8. **Enable diagnostic settings** - Essential for troubleshooting and compliance
+
+## Common Patterns
+
+### Development Environment
+
+```typescript
+// Relaxed thresholds for dev
+monitoring: VirtualMachine.defaultMonitoring(
+  devActionGroup.id,
+  devWorkspace.id,
+  {
+    cpuThreshold: 95,
+    enableDeletionAlert: false,
+  }
+)
+```
+
+### Production Environment
+
+```typescript
+// Stricter thresholds with critical severity
+monitoring: VirtualMachine.defaultMonitoring(
+  prodActionGroup.id,
+  prodWorkspace.id,
+  {
+    cpuThreshold: 80,
+    memoryThreshold: 1073741824,
+    cpuAlertSeverity: 0,  // Critical
+    memoryAlertSeverity: 0,  // Critical
+  }
+)
+```
+
+### Monitoring Disabled
+
+```typescript
+// Explicitly disable monitoring
+monitoring: {
+  enabled: false
+}
+```
+
+## Related Documentation
+
+- [Azure Monitor Documentation](https://learn.microsoft.com/en-us/azure/azure-monitor/)
+- [Metric Alerts](../src/azure-metricalert/README.md)
+- [Action Groups](../src/azure-actiongroup/README.md)
+- [Diagnostic Settings](../src/azure-diagnosticsettings/README.md)
+- [Activity Log Alerts](../src/azure-activitylogalert/README.md)

package/docs/testing.md

@@ -244,6 +244,89 @@ The integration test will perform the following against the example file:
     - This step removes the test environment and ensures the infrastructure can be cleanly deleted.
     - It's designed to catch common problems that occur when removing infrastructure, especially those related to resource dependencies.
 
+### Integration Test Resource Management
+
+All integration tests use an enhanced resource management system that provides:
+
+- **Unique Naming**: Automatically generated, collision-free resource names
+- **System Tags**: 15+ metadata tags for tracking and cleanup
+- **Cleanup Verification**: Post-destroy validation ensures resources are completely removed
+- **Cost Control**: Automated cleanup prevents orphaned resources
+
+#### Quick Example
+
+```typescript
+import { Testing } from "cdktf";
+import { BaseTestStack, TerraformApplyCheckAndDestroy } from "../../testing";
+import { TestRunMetadata } from "../../testing/lib/metadata";
+import { ResourceGroup } from "../../azure-resourcegroup";
+
+// Generate unique test run metadata
+const testMetadata = new TestRunMetadata("my-test-integration", {
+  maxAgeHours: 4,
+});
+
+class MyTestStack extends BaseTestStack {
+  constructor(scope: Construct, id: string) {
+    super(scope, id, {
+      testRunOptions: {
+        maxAgeHours: testMetadata.maxAgeHours,
+        autoCleanup: testMetadata.autoCleanup,
+        cleanupPolicy: testMetadata.cleanupPolicy,
+      },
+    });
+
+    // Generate unique name
+    const rgName = this.generateResourceName(
+      "Microsoft.Resources/resourceGroups",
+      "my-test",
+    );
+
+    // Create resource with system tags
+    new ResourceGroup(this, "rg", {
+      name: rgName,
+      location: "eastus",
+      tags: {
+        ...this.getSystemTags(),  // System tags for tracking
+        myCustomTag: "value",      // Your custom tags
+      },
+    });
+  }
+}
+
+describe("My Test", () => {
+  it("should deploy and cleanup resources", () => {
+    const app = Testing.app();
+    const stack = new MyTestStack(app, "test");
+    const synthesized = Testing.fullSynth(stack);
+    
+    // Enable cleanup verification
+    TerraformApplyCheckAndDestroy(synthesized, { verifyCleanup: true });
+  }, 600000);
+});
+```
+
+#### Key Benefits
+
+✅ **No Name Conflicts**: Tests can run in parallel without collision
+✅ **Automatic Cleanup**: Resources are properly destroyed after tests
+✅ **Cost Control**: Manual cleanup script removes orphaned resources
+✅ **Traceability**: Track resources back to specific test runs and commits
+
+#### Manual Cleanup
+
+Remove orphaned resources from failed tests:
+
+```bash
+# Preview what would be deleted (dry run)
+npx ts-node scripts/cleanup-test-resources.ts --dry-run
+
+# Delete orphaned resources older than 2 hours
+npx ts-node scripts/cleanup-test-resources.ts
+```
+
+For comprehensive documentation, see the [Integration Test Resource Management Guide](./integration-test-resource-management-guide.md).
+
 ## End to End Tests
 
-End to End tests are used when testing a class that contains multiple stacks. The workflow is the same as with integration tests, however the test will take much longer. 
+End to End tests are used when testing a class that contains multiple stacks. The workflow is the same as with integration tests, however the test will take much longer.

package/lib/azure-actiongroup/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Azure Action Group construct
+ *
+ * This module provides the Action Group construct for Azure Monitor alerts.
+ * Action Groups serve as the central notification hub, supporting multiple
+ * receiver types including email, SMS, webhook, Azure Functions, Logic Apps,
+ * and voice calls.
+ *
+ * @packageDocumentation
+ */
+export * from "./lib";

package/lib/azure-actiongroup/index.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Azure Action Group construct
+ *
+ * This module provides the Action Group construct for Azure Monitor alerts.
+ * Action Groups serve as the central notification hub, supporting multiple
+ * receiver types including email, SMS, webhook, Azure Functions, Logic Apps,
+ * and voice calls.
+ *
+ * @packageDocumentation
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./lib"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvYXp1cmUtYWN0aW9uZ3JvdXAvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBOzs7Ozs7Ozs7R0FTRzs7Ozs7Ozs7Ozs7Ozs7OztBQUVILHdDQUFzQiIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogQXp1cmUgQWN0aW9uIEdyb3VwIGNvbnN0cnVjdFxuICpcbiAqIFRoaXMgbW9kdWxlIHByb3ZpZGVzIHRoZSBBY3Rpb24gR3JvdXAgY29uc3RydWN0IGZvciBBenVyZSBNb25pdG9yIGFsZXJ0cy5cbiAqIEFjdGlvbiBHcm91cHMgc2VydmUgYXMgdGhlIGNlbnRyYWwgbm90aWZpY2F0aW9uIGh1Yiwgc3VwcG9ydGluZyBtdWx0aXBsZVxuICogcmVjZWl2ZXIgdHlwZXMgaW5jbHVkaW5nIGVtYWlsLCBTTVMsIHdlYmhvb2ssIEF6dXJlIEZ1bmN0aW9ucywgTG9naWMgQXBwcyxcbiAqIGFuZCB2b2ljZSBjYWxscy5cbiAqXG4gKiBAcGFja2FnZURvY3VtZW50YXRpb25cbiAqL1xuXG5leHBvcnQgKiBmcm9tIFwiLi9saWJcIjtcbiJdfQ==

package/lib/azure-actiongroup/lib/action-group-schemas.d.ts

@@ -0,0 +1,24 @@
+/**
+ * API schemas for Azure Action Group across all supported versions
+ *
+ * This file defines the complete API schemas for Microsoft.Insights/actionGroups
+ * across all supported API versions. The schemas are used by the AzapiResource
+ * framework for validation, transformation, and version management.
+ */
+import { ApiSchema, VersionConfig } from "../../core-azure/lib/version-manager/interfaces/version-interfaces";
+/**
+ * API Schema for Action Group version 2021-09-01
+ */
+export declare const ACTION_GROUP_SCHEMA_2021_09_01: ApiSchema;
+/**
+ * Version configuration for Action Group 2021-09-01
+ */
+export declare const ACTION_GROUP_VERSION_2021_09_01: VersionConfig;
+/**
+ * All supported Action Group versions for registration
+ */
+export declare const ALL_ACTION_GROUP_VERSIONS: VersionConfig[];
+/**
+ * Resource type constant
+ */
+export declare const ACTION_GROUP_TYPE = "Microsoft.Insights/actionGroups";