@microsoft/terraform-cdk-constructs 0.0.3-pre.7 → 1.0.0

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

@@ -0,0 +1,413 @@
+/**
+ * AzapiResource - A unified framework for version-aware Azure resource management
+ *
+ * This abstract base class provides a self-contained unified framework approach
+ * for Azure resource management with automatic version management, schema-driven
+ * property transformation, and migration analysis capabilities.
+ *
+ * Key Features:
+ * - Automatic latest version resolution when no version is specified
+ * - Support for explicit version pinning for stability
+ * - Schema-driven property transformation between versions
+ * - Migration analysis and deprecation warnings
+ * - Built-in role assignment and diagnostic settings support
+ * - JSII-compliant design for multi-language support
+ *
+ * This class replaces the previous dual-class approach (AzapiResource + AzapiResource)
+ * with a single, self-contained implementation that handles all resource management needs.
+ *
+ * @packageDocumentation
+ */
+import * as cdktf from "cdktf";
+import { Construct } from "constructs";
+import { ApiSchema, VersionConfig, ValidationResult, MigrationAnalysis } from "../version-manager/interfaces/version-interfaces";
+/**
+ * Retention policy configuration
+ */
+export interface RetentionPolicyConfig {
+    readonly enabled: boolean;
+    readonly days: number;
+}
+/**
+ * Log configuration for diagnostic settings
+ */
+export interface DiagnosticLogConfig {
+    readonly category?: string;
+    readonly categoryGroup?: string;
+    readonly enabled: boolean;
+    readonly retentionPolicy?: RetentionPolicyConfig;
+}
+/**
+ * Metric configuration for diagnostic settings
+ */
+export interface DiagnosticMetricConfig {
+    readonly category: string;
+    readonly enabled: boolean;
+    readonly retentionPolicy?: RetentionPolicyConfig;
+}
+/**
+ * Properties for versioned Azure resources
+ *
+ * Combines base resource properties with version management capabilities
+ * and advanced configuration options for the unified framework.
+ */
+export interface AzapiResourceProps {
+    /**
+     * The name of the resource
+     */
+    readonly name?: string;
+    /**
+     * The location where the resource should be created
+     */
+    readonly location?: string;
+    /**
+     * Tags to apply to the resource
+     */
+    readonly tags?: Record<string, string>;
+    /**
+     * Explicit API version to use for this resource
+     *
+     * If not specified, the latest active version will be automatically resolved.
+     * Use this for version pinning when stability is required over latest features.
+     *
+     * @example "2024-11-01"
+     * @defaultValue Latest active version from ApiVersionManager
+     */
+    readonly apiVersion?: string;
+    /**
+     * Whether to enable migration analysis warnings
+     *
+     * When true, the framework will analyze the current version for deprecation
+     * status and provide migration recommendations in the deployment output.
+     *
+     * @defaultValue true
+     */
+    readonly enableMigrationAnalysis?: boolean;
+    /**
+     * Whether to validate properties against the schema
+     *
+     * When true, all properties will be validated against the API schema before
+     * resource creation. Validation errors will cause deployment failures.
+     *
+     * @defaultValue true
+     */
+    readonly enableValidation?: boolean;
+    /**
+     * Whether to apply property transformations automatically
+     *
+     * When true, properties will be automatically transformed according to the
+     * target schema's transformation rules. This enables backward compatibility.
+     *
+     * @defaultValue true
+     */
+    readonly enableTransformation?: boolean;
+}
+/**
+ * Abstract base class for version-aware Azure resource management
+ *
+ * AzapiResource provides a unified framework for creating Azure resources
+ * with automatic version management, schema validation, property transformation,
+ * and migration analysis. It extends the existing AzapiResource class while
+ * maintaining full backward compatibility.
+ *
+ * This class implements the core framework that enables:
+ * - Automatic resolution of the latest API version when none is specified
+ * - Explicit version pinning for environments requiring stability
+ * - Schema-driven property validation and transformation
+ * - Migration analysis with breaking change detection
+ * - Deprecation warnings and upgrade recommendations
+ *
+ * Subclasses must implement the abstract methods to provide resource-specific
+ * configuration while the framework handles all version management complexity.
+ *
+ * @example Basic usage with automatic version resolution:
+ * class MyResource extends AzapiResource {
+ *   protected getDefaultVersion(): string {
+ *     return "2024-11-01"; // fallback if no versions registered
+ *   }
+ *
+ *   protected getResourceType(): string {
+ *     return "Microsoft.Resources/resourceGroups";
+ *   }
+ *
+ *   protected getApiSchema(): ApiSchema {
+ *     return this.resolveSchema();
+ *   }
+ *
+ *   protected createResourceBody(props: any): any {
+ *     return { location: props.location, tags: props.tags || {} };
+ *   }
+ * }
+ *
+ * @example Usage with explicit version pinning:
+ * new MyResource(this, "resource", {
+ *   name: "my-resource",
+ *   location: "eastus",
+ *   apiVersion: "2024-01-01" // Pin to specific version
+ * });
+ *
+ * @stability stable
+ */
+export declare abstract class AzapiResource extends Construct {
+    /**
+     * The Azure resource type (e.g., "Microsoft.Resources/resourceGroups")
+     * @internal
+     */
+    protected readonly _resourceType: string;
+    /**
+     * The API version to use for this resource
+     */
+    protected readonly apiVersion: string;
+    /**
+     * The underlying AZAPI Terraform resource
+     */
+    protected terraformResource: cdktf.TerraformResource;
+    /**
+     * The name of the resource
+     */
+    readonly name: string;
+    /**
+     * The location of the resource
+     */
+    readonly location: string;
+    /**
+     * The resource ID (abstract - must be implemented by subclasses)
+     */
+    abstract readonly id: string;
+    /**
+     * The resolved API version being used for this resource instance
+     *
+     * This is the actual version that will be used for the Azure API call,
+     * either explicitly specified in props or automatically resolved to
+     * the latest active version.
+     */
+    readonly 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;
+    /**
+     * The version configuration for the resolved version
+     *
+     * Contains lifecycle information, breaking changes, and migration metadata
+     * for the resolved API version.
+     */
+    readonly 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;
+    /**
+     * Migration analysis results
+     *
+     * Available after construction if migration analysis is enabled and a
+     * previous version can be determined for comparison.
+     */
+    readonly migrationAnalysis?: MigrationAnalysis;
+    private readonly _apiVersionManager;
+    private readonly _schemaMapper;
+    /**
+     * Creates a new AzapiResource instance
+     *
+     * The constructor handles all framework initialization including version resolution,
+     * schema loading, property validation, transformation, and migration analysis.
+     * It maintains full backward compatibility with the AzapiResource constructor.
+     *
+     * @param scope - The scope in which to define this construct
+     * @param id - The unique identifier for this instance
+     * @param props - Configuration properties for the resource
+     */
+    constructor(scope: Construct, id: string, props?: AzapiResourceProps);
+    /**
+     * Gets the default API version to use when no explicit version is specified
+     *
+     * This method should return a sensible default version that can be used
+     * as a fallback if the ApiVersionManager doesn't have any versions registered
+     * for this resource type.
+     *
+     * @returns The default API version string (e.g., "2024-11-01")
+     */
+    protected abstract defaultVersion(): string;
+    /**
+     * Gets the Azure resource type for this resource
+     *
+     * This method should return the full Azure resource type identifier that
+     * will be used for API calls and version management.
+     *
+     * @returns The Azure resource type (e.g., "Microsoft.Resources/resourceGroups")
+     */
+    protected abstract resourceType(): string;
+    /**
+     * Gets the API schema for the resolved version
+     *
+     * This method should return the complete API schema for the resolved version,
+     * including all property definitions, validation rules, and transformation
+     * mappings. Use the resolveSchema() helper method for standard schema resolution.
+     *
+     * @returns The API schema for the resolved version
+     */
+    protected abstract apiSchema(): ApiSchema;
+    /**
+     * Creates the resource body for the Azure API call
+     *
+     * This method should transform the input properties into the JSON body format
+     * expected by the Azure REST API for the resolved version. The framework will
+     * have already applied any necessary property transformations and validation.
+     *
+     * @param props - The processed and validated properties for the resource
+     * @returns The resource body object to send to Azure API
+     */
+    protected abstract createResourceBody(props: any): any;
+    /**
+     * Helper method for standard schema resolution
+     *
+     * Subclasses can use this method to resolve the schema for the current version
+     * from the ApiVersionManager. This provides a standard implementation that
+     * most resources can use without custom logic.
+     *
+     * @returns The API schema for the resolved version
+     * @throws Error if the schema cannot be resolved
+     */
+    protected resolveSchema(): ApiSchema;
+    /**
+     * Gets the latest available version for this resource type
+     *
+     * This method provides access to the latest version resolution logic
+     * for use in subclasses or external tooling.
+     *
+     * @returns The latest available version, or undefined if none found
+     */
+    latestVersion(): string | undefined;
+    /**
+     * Gets all supported versions for this resource type
+     *
+     * This method provides access to the version registry for use in
+     * subclasses or external tooling.
+     *
+     * @returns Array of supported version strings, sorted by release date
+     */
+    supportedVersions(): string[];
+    /**
+     * Analyzes migration from current version to a target version
+     *
+     * This method enables external tools to analyze migration requirements
+     * between versions for planning and automation purposes.
+     *
+     * @param targetVersion - The target version to analyze migration to
+     * @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
+     */
+    private _performMigrationAnalysis;
+    /**
+     * Creates the underlying Azure resource
+     */
+    private _createAzureResource;
+    /**
+     * Determines the parent ID for the resource
+     */
+    private _determineParentId;
+    /**
+     * Logs framework messages including warnings and migration guidance
+     */
+    private _logFrameworkMessages;
+    /**
+     * Creates the underlying AZAPI Terraform resource using the generated provider classes
+     *
+     * @param properties - The properties object to send to the Azure API
+     * @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)
+     * @returns The created AZAPI resource
+     */
+    protected createAzapiResource(properties: Record<string, any>, parentId: string, name: string, location?: string): cdktf.TerraformResource;
+    /**
+     * Creates an AZAPI data source for reading existing resources
+     *
+     * @param resourceId - The full resource ID
+     * @returns The created Terraform data source
+     */
+    protected createAzapiDataSource(resourceId: string): cdktf.TerraformDataSource;
+    /**
+     * Updates the resource with new properties
+     *
+     * @param properties - The new properties to apply
+     */
+    protected updateAzapiResource(properties: Record<string, any>): void;
+    /**
+     * Gets the full resource ID
+     */
+    get resourceId(): string;
+    /**
+     * Gets the resource as a Terraform output value
+     */
+    get output(): cdktf.TerraformOutput;
+    /**
+     * Adds an access role assignment for a specified Azure AD object
+     *
+     * Note: This method creates role assignments using AZAPI instead of AzureRM provider.
+     *
+     * @param objectId - The unique identifier of the Azure AD object
+     * @param roleDefinitionName - The name of the Azure RBAC role to be assigned
+     */
+    addAccess(objectId: string, roleDefinitionName: string): void;
+    /**
+     * Adds diagnostic settings to this resource using AZAPI
+     *
+     * @param props - The diagnostic settings configuration
+     */
+    addDiagnosticSettings(props: AzapiDiagnosticSettingsProps): AzapiDiagnosticSettings;
+}
+/**
+ * Properties for AZAPI role assignment
+ */
+export interface AzapiRoleAssignmentProps {
+    readonly objectId: string;
+    readonly roleDefinitionName: string;
+    readonly scope: string;
+}
+/**
+ * AZAPI-based role assignment construct
+ */
+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);
+}