@microsoft/terraform-cdk-constructs 1.0.0 → 1.3.0

package/lib/core-azure/lib/azapi/azapi-resource.d.ts

@@ -20,6 +20,10 @@
  */
 import * as cdktf from "cdktf";
 import { Construct } from "constructs";
+import type { ActionGroupProps } from "../../../azure-actiongroup/lib/action-group";
+import type { ActivityLogAlertProps } from "../../../azure-activitylogalert/lib/activity-log-alert";
+import type { DiagnosticSettingsProps } from "../../../azure-diagnosticsettings/lib/diagnostic-settings";
+import type { MetricAlertProps } from "../../../azure-metricalert/lib/metric-alert";
 import { ApiSchema, VersionConfig, ValidationResult, MigrationAnalysis } from "../version-manager/interfaces/version-interfaces";
 /**
  * Retention policy configuration
@@ -41,23 +45,83 @@ export interface DiagnosticLogConfig {
  * Metric configuration for diagnostic settings
  */
 export interface DiagnosticMetricConfig {
-    readonly category: string;
+    /** Metric category name (used in newer API versions) */
+    readonly category?: string;
+    /** Time grain for metrics in ISO 8601 duration format (used in API version 2016-09-01, e.g., "PT1M") */
+    readonly timeGrain?: string;
     readonly enabled: boolean;
     readonly retentionPolicy?: RetentionPolicyConfig;
 }
+/**
+ * Monitoring configuration for Azure resources
+ *
+ * Provides integrated monitoring capabilities including diagnostic settings,
+ * metric alerts, and activity log alerts. All monitoring is optional and
+ * disabled by default.
+ */
+export interface MonitoringConfig {
+    /**
+     * Whether monitoring is enabled
+     * @defaultValue true
+     */
+    readonly enabled?: boolean;
+    /**
+     * Diagnostic settings configuration
+     * Uses the full DiagnosticSettings construct for consistency
+     */
+    readonly diagnosticSettings?: DiagnosticSettingsProps;
+    /**
+     * Action groups to create for this resource
+     * Creates new ActionGroup instances as child constructs
+     */
+    readonly actionGroups?: ActionGroupProps[];
+    /**
+     * Metric alerts configuration
+     * Creates MetricAlert instances scoped to this resource
+     */
+    readonly metricAlerts?: MetricAlertProps[];
+    /**
+     * Activity log alerts configuration
+     * Creates ActivityLogAlert instances for this resource's operations
+     */
+    readonly activityLogAlerts?: ActivityLogAlertProps[];
+}
 /**
  * Properties for versioned Azure resources
  *
  * Combines base resource properties with version management capabilities
  * and advanced configuration options for the unified framework.
  */
-export interface AzapiResourceProps {
+export interface AzapiResourceProps extends cdktf.TerraformMetaArguments {
     /**
      * The name of the resource
      */
     readonly name?: string;
     /**
      * The location where the resource should be created
+     *
+     * @remarks
+     * Location handling varies by resource type:
+     * - **Top-level resources**: Most require an explicit location (e.g., "eastus", "westus")
+     * - **Global resources**: Some use "global" as location (e.g., Private DNS Zones)
+     * - **Child resources**: Inherit location from parent and should NOT set this property
+     *
+     * Each resource type may provide its own default through the `resolveLocation()` method.
+     * If no location is specified and no default exists, resource creation may fail.
+     *
+     * @example
+     * // Explicit location for most resources
+     * location: "eastus"
+     *
+     * @example
+     * // Global resource (Private DNS Zone)
+     * location: "global"
+     *
+     * @example
+     * // Child resource (Subnet) - do not set location
+     * // location: undefined (inherited from parent Virtual Network)
+     *
+     * @defaultValue Varies by resource type - see specific resource documentation
      */
     readonly location?: string;
     /**
@@ -101,6 +165,30 @@ export interface AzapiResourceProps {
      * @defaultValue true
      */
     readonly enableTransformation?: boolean;
+    /**
+     * Monitoring configuration for this resource
+     *
+     * Enables integrated monitoring with diagnostic settings, metric alerts,
+     * and activity log alerts. All monitoring is optional and disabled by default.
+     *
+     * @example
+     * monitoring: {
+     *   enabled: true,
+     *   diagnosticSettings: {
+     *     workspaceId: logAnalytics.id,
+     *     metrics: ['AllMetrics'],
+     *     logs: ['AuditLogs']
+     *   },
+     *   metricAlerts: [{
+     *     name: 'high-cpu-alert',
+     *     severity: 2,
+     *     scopes: [], // Automatically set to this resource
+     *     criteria: { ... },
+     *     actions: [{ actionGroupId: actionGroup.id }]
+     *   }]
+     * }
+     */
+    readonly monitoring?: MonitoringConfig;
 }
 /**
  * Abstract base class for version-aware Azure resource management
@@ -149,15 +237,35 @@ export interface AzapiResourceProps {
  * @stability stable
  */
 export declare abstract class AzapiResource extends Construct {
+    /**
+     * Static helper for child classes to register their schemas in static initializers
+     *
+     * This method should be called in a static initializer block of each child class
+     * to register all supported API versions and their schemas with the ApiVersionManager.
+     * The static block runs once when the class is first loaded, ensuring schemas are
+     * registered before any instances are created.
+     *
+     * @param resourceType - The Azure resource type (e.g., "Microsoft.Network/virtualNetworks")
+     * @param versions - Array of version configurations containing schemas
+     *
+     * @example
+     * static {
+     *   AzapiResource.registerSchemas(
+     *     "Microsoft.Network/virtualNetworks",
+     *     ALL_VIRTUAL_NETWORK_VERSIONS
+     *   );
+     * }
+     */
+    protected static registerSchemas(resourceType: string, versions: VersionConfig[]): void;
     /**
      * The Azure resource type (e.g., "Microsoft.Resources/resourceGroups")
      * @internal
      */
-    protected readonly _resourceType: string;
+    protected _resourceType: string;
     /**
      * The API version to use for this resource
      */
-    protected readonly apiVersion: string;
+    protected apiVersion: string;
     /**
      * The underlying AZAPI Terraform resource
      */
@@ -167,13 +275,17 @@ export declare abstract class AzapiResource extends Construct {
      */
     readonly name: string;
     /**
-     * The location of the resource
+     * The location of the resource (optional - not all resources have a location)
+     * Child resources typically inherit location from their parent
      */
-    readonly location: string;
+    readonly location?: string;
     /**
-     * The resource ID (abstract - must be implemented by subclasses)
+     * The Azure resource ID
+     *
+     * This property is automatically derived from the underlying Terraform resource.
+     * Child classes no longer need to implement this property.
      */
-    abstract readonly id: string;
+    get id(): string;
     /**
      * The resolved API version being used for this resource instance
      *
@@ -181,37 +293,46 @@ export declare abstract class AzapiResource extends Construct {
      * either explicitly specified in props or automatically resolved to
      * the latest active version.
      */
-    readonly resolvedApiVersion: string;
+    resolvedApiVersion: string;
     /**
      * The API schema for the resolved version
      *
      * Contains the complete schema definition including properties, validation
      * rules, and transformation mappings for the resolved API version.
      */
-    readonly schema: ApiSchema;
+    schema: ApiSchema;
     /**
      * The version configuration for the resolved version
      *
      * Contains lifecycle information, breaking changes, and migration metadata
      * for the resolved API version.
      */
-    readonly versionConfig: VersionConfig;
+    versionConfig: VersionConfig;
     /**
      * Validation results for the resource properties
      *
      * Available after construction if validation is enabled. Contains detailed
      * information about any validation errors or warnings.
      */
-    readonly validationResult?: ValidationResult;
+    validationResult?: ValidationResult;
     /**
      * Migration analysis results
      *
      * Available after construction if migration analysis is enabled and a
      * previous version can be determined for comparison.
      */
-    readonly migrationAnalysis?: MigrationAnalysis;
+    migrationAnalysis?: MigrationAnalysis;
     private readonly _apiVersionManager;
-    private readonly _schemaMapper;
+    private _versionManager;
+    private _schemaValidator;
+    /**
+     * Internal mutable tags storage separate from input props
+     * Combines props.tags with dynamically added tags via addTag()
+     */
+    private _tags;
+    protected readonly monitoringActionGroups: Construct[];
+    protected readonly monitoringMetricAlerts: Construct[];
+    protected readonly monitoringActivityLogAlerts: Construct[];
     /**
      * Creates a new AzapiResource instance
      *
@@ -224,6 +345,16 @@ export declare abstract class AzapiResource extends Construct {
      * @param props - Configuration properties for the resource
      */
     constructor(scope: Construct, id: string, props?: AzapiResourceProps);
+    /**
+     * Protected initialization method called after the constructor completes
+     *
+     * This method is called at the end of the constructor to perform initialization
+     * that requires calling abstract methods. Child classes can override this method
+     * if they need to extend initialization logic, but they MUST call super.initialize(props).
+     *
+     * @param props - Configuration properties for the resource
+     */
+    protected initialize(props: AzapiResourceProps): void;
     /**
      * Gets the default API version to use when no explicit version is specified
      *
@@ -264,6 +395,36 @@ export declare abstract class AzapiResource extends Construct {
      * @returns The resource body object to send to Azure API
      */
     protected abstract createResourceBody(props: any): any;
+    /**
+     * Override in child classes to provide default location
+     * @returns Default location or undefined
+     */
+    protected defaultLocation(): string | undefined;
+    /**
+     * Override in child classes to indicate if location is required
+     * @returns true if location is mandatory for this resource type
+     */
+    protected requiresLocation(): boolean;
+    /**
+     * Override in child classes to specify parent resource for location inheritance
+     * @returns Parent resource or undefined
+     */
+    protected parentResourceForLocation(): AzapiResource | undefined;
+    /**
+     * Resolves location using template method pattern
+     * Priority: props.location > parent location > default location > validation
+     */
+    protected resolveLocation(props: AzapiResourceProps): string | undefined;
+    /**
+     * Resolves the name for this resource
+     *
+     * This method centralizes name resolution logic. By default, it uses the
+     * provided name or falls back to the construct ID.
+     *
+     * @param props - The resource properties
+     * @returns The resolved resource name
+     */
+    protected resolveName(props: AzapiResourceProps): string;
     /**
      * Helper method for standard schema resolution
      *
@@ -303,18 +464,10 @@ export declare abstract class AzapiResource extends Construct {
      * @returns Detailed migration analysis results
      */
     analyzeMigrationTo(targetVersion: string): MigrationAnalysis;
-    /**
-     * Resolves the API version to use for this resource instance
-     */
-    private _resolveApiVersion;
     /**
      * Processes properties through the framework pipeline
      */
     private _processProperties;
-    /**
-     * Validates properties against the schema
-     */
-    private _validateProperties;
     /**
      * Performs migration analysis for the current version
      */
@@ -324,23 +477,72 @@ export declare abstract class AzapiResource extends Construct {
      */
     private _createAzureResource;
     /**
-     * Determines the parent ID for the resource
+     * Finds the parent AzapiResource construct if the parentId references a resource
+     * Returns undefined if parentId is a static string or parent not found
+     * @private
+     */
+    private _findParentAzapiResource;
+    /**
+     * Finds the root of the construct tree
+     * @private
+     */
+    private _findRoot;
+    /**
+     * Recursively searches for a parent resource by matching parentId patterns
+     * Enhanced to better handle Terraform interpolation syntax
+     * @private
+     */
+    private _findParentResource;
+    /**
+     * Resolves the parent resource ID for this resource.
+     *
+     * Override this method in child resource classes (like Subnet) that need
+     * custom parent ID resolution logic. By default, this delegates to the
+     * private _determineParentId method which handles standard resource types.
+     *
+     * @param props - The resource properties
+     * @returns The parent resource ID
+     */
+    protected resolveParentId(props: any): string;
+    /**
+     * Determines the parent ID for the resource (internal implementation)
+     *
+     * This method provides the default parent ID resolution logic.
+     * Resource-specific logic should be implemented in the overrideable resolveParentId() method.
+     *
+     * Default behavior:
+     * - If resourceGroupId is provided in props, use it
+     * - Otherwise, default to subscription scope
      */
     private _determineParentId;
     /**
      * Logs framework messages including warnings and migration guidance
      */
     private _logFrameworkMessages;
+    /**
+     * Creates monitoring resources based on the monitoring configuration
+     *
+     * This method is called automatically during construction if monitoring is configured.
+     * It creates action groups, metric alerts, and activity log alerts as child constructs.
+     *
+     * Protected to allow subclasses to override or extend monitoring behavior.
+     *
+     * @param config - The monitoring configuration from props
+     */
+    protected createMonitoringResources(config: MonitoringConfig): Promise<void>;
     /**
      * Creates the underlying AZAPI Terraform resource using the generated provider classes
      *
-     * @param properties - The properties object to send to the Azure API
+     * @param properties - The properties object to send to the Azure API (should include location if needed)
      * @param parentId - The parent resource ID (e.g., subscription or resource group)
      * @param name - The name of the resource
-     * @param location - The location of the resource (optional, can be in properties)
+     * @param location - The location of the resource (optional, only for top-level resources without location in body)
+     * @param parentResource - The parent resource for dependency tracking
+     * @param dependsOn - Explicit dependencies for this resource
+     * @param tags - Tags to apply to the resource (passed separately from body for proper idempotency)
      * @returns The created AZAPI resource
      */
-    protected createAzapiResource(properties: Record<string, any>, parentId: string, name: string, location?: string): cdktf.TerraformResource;
+    protected createAzapiResource(properties: Record<string, any>, parentId: string, name: string, location?: string, parentResource?: AzapiResource, dependsOn?: cdktf.ITerraformDependable[], tags?: Record<string, string>): cdktf.TerraformResource;
     /**
      * Creates an AZAPI data source for reading existing resources
      *
@@ -358,6 +560,11 @@ export declare abstract class AzapiResource extends Construct {
      * Gets the full resource ID
      */
     get resourceId(): string;
+    /**
+     * Gets the underlying Terraform resource for use in dependency declarations
+     * This allows explicit dependency management between resources
+     */
+    get resource(): cdktf.TerraformResource;
     /**
      * Gets the resource as a Terraform output value
      */
@@ -372,11 +579,43 @@ export declare abstract class AzapiResource extends Construct {
      */
     addAccess(objectId: string, roleDefinitionName: string): void;
     /**
-     * Adds diagnostic settings to this resource using AZAPI
+     * Adds a tag to this resource. The tag will be included in the Azure resource.
+     *
+     * This method provides proper immutability by storing tags separately from props.
+     * Tags added via this method are combined with tags from props and included in
+     * the deployed Azure resource.
+     *
+     * **Important:** In CDK for Terraform, tags should ideally be set during resource
+     * construction via props. While this method allows adding tags after construction,
+     * those tags are only included if added before the Terraform configuration is
+     * synthesized. For best results, add all tags via props or call addTag() in the
+     * same scope where the resource is created.
+     *
+     * @param key - The tag key
+     * @param value - The tag value
+     */
+    addTag(key: string, value: string): void;
+    /**
+     * All tags on this resource (readonly view)
      *
-     * @param props - The diagnostic settings configuration
+     * This getter provides convenient access to all tags including those from props
+     * and those added dynamically via addTag(). Returns a copy to maintain immutability.
      */
-    addDiagnosticSettings(props: AzapiDiagnosticSettingsProps): AzapiDiagnosticSettings;
+    get tags(): {
+        [key: string]: string;
+    };
+    /**
+     * Protected method to retrieve all tags for use in createResourceBody implementations
+     *
+     * Subclasses should use this method when creating resource bodies to ensure
+     * all tags (from props and addTag()) are included in the Azure resource.
+     * Uses a non-getter name to avoid JSII conflicts with the tags property.
+     *
+     * @returns Object containing all tags
+     */
+    protected allTags(): {
+        [key: string]: string;
+    };
 }
 /**
  * Properties for AZAPI role assignment
@@ -392,22 +631,3 @@ export interface AzapiRoleAssignmentProps {
 export declare class AzapiRoleAssignment extends Construct {
     constructor(scope: Construct, id: string, props: AzapiRoleAssignmentProps);
 }
-/**
- * Properties for AZAPI diagnostic settings
- */
-export interface AzapiDiagnosticSettingsProps {
-    readonly name?: string;
-    readonly logAnalyticsWorkspaceId?: string;
-    readonly eventhubAuthorizationRuleId?: string;
-    readonly eventhubName?: string;
-    readonly storageAccountId?: string;
-    readonly targetResourceId?: string;
-    readonly logs?: DiagnosticLogConfig[];
-    readonly metrics?: DiagnosticMetricConfig[];
-}
-/**
- * AZAPI-based diagnostic settings construct
- */
-export declare class AzapiDiagnosticSettings extends Construct {
-    constructor(scope: Construct, id: string, props: AzapiDiagnosticSettingsProps);
-}