@microsoft/terraform-cdk-constructs 1.0.0 → 1.2.0

package/lib/azure-aks/lib/aks-cluster.d.ts

@@ -0,0 +1,395 @@
+/**
+ * Unified Azure Kubernetes Service (AKS) implementation using VersionedAzapiResource framework
+ *
+ * This class provides a single, version-aware implementation for AKS clusters that automatically
+ * handles version management, schema validation, and property transformation across all supported
+ * API versions.
+ *
+ * Supported API Versions:
+ * - 2024-10-01 (Active)
+ * - 2025-01-01 (Active)
+ * - 2025-07-01 (Active, Latest)
+ *
+ * Features:
+ * - Automatic latest version resolution when no version is specified
+ * - Explicit version pinning for stability requirements
+ * - Schema-driven validation and transformation
+ * - Full JSII compliance for multi-language support
+ * - Comprehensive support for AKS features (networking, security, scaling, etc.)
+ */
+import * as cdktf from "cdktf";
+import { Construct } from "constructs";
+import { AksClusterSku, AksClusterIdentity, AksClusterAgentPoolProfile, AksClusterNetworkProfile, AksClusterServicePrincipalProfile, AksClusterApiServerAccessProfile, AksClusterAutoScalerProfile, AksClusterWindowsProfile, AksClusterLinuxProfile, AksClusterAadProfile, AksClusterAddonProfiles, AksClusterOidcIssuerProfile, AksClusterSecurityProfile, AksClusterStorageProfile, AksClusterHttpProxyConfig, AksClusterWorkloadAutoScalerProfile, AksClusterMonitoringOptions } from "./aks-cluster-schemas";
+import { AzapiResource, AzapiResourceProps, MonitoringConfig } from "../../core-azure/lib/azapi/azapi-resource";
+import { ApiSchema } from "../../core-azure/lib/version-manager/interfaces/version-interfaces";
+/**
+ * Properties for the unified Azure Kubernetes Service cluster
+ *
+ * Extends AzapiResourceProps with AKS-specific properties
+ */
+export interface AksClusterProps extends AzapiResourceProps {
+    /**
+     * The SKU (pricing tier) for the AKS cluster
+     * @example { name: "Base", tier: "Free" }
+     * @example { name: "Standard", tier: "Standard" }
+     */
+    readonly sku?: AksClusterSku;
+    /**
+     * The identity configuration for the AKS cluster
+     * @example { type: "SystemAssigned" }
+     * @example { type: "UserAssigned", userAssignedIdentities: { "/subscriptions/.../resourceGroups/.../providers/Microsoft.ManagedIdentity/userAssignedIdentities/myIdentity": {} } }
+     */
+    readonly identity?: AksClusterIdentity;
+    /**
+     * The Kubernetes version for the cluster
+     * @example "1.28.3"
+     * @example "1.29.0"
+     */
+    readonly kubernetesVersion?: string;
+    /**
+     * DNS prefix for the cluster
+     * @example "myakscluster"
+     */
+    readonly dnsPrefix: string;
+    /**
+     * The FQDN for the cluster (read-only)
+     */
+    readonly fqdn?: string;
+    /**
+     * The private FQDN for the cluster (read-only)
+     */
+    readonly privateFQDN?: string;
+    /**
+     * The agent pool profiles for the cluster node pools
+     * At least one agent pool is required
+     * @example [{ name: "default", count: 3, vmSize: "Standard_D2s_v3", mode: "System" }]
+     */
+    readonly agentPoolProfiles: AksClusterAgentPoolProfile[];
+    /**
+     * The service principal profile for the cluster
+     */
+    readonly servicePrincipalProfile?: AksClusterServicePrincipalProfile;
+    /**
+     * The network configuration for the cluster
+     */
+    readonly networkProfile?: AksClusterNetworkProfile;
+    /**
+     * The Azure Active Directory integration configuration
+     */
+    readonly aadProfile?: AksClusterAadProfile;
+    /**
+     * The auto-scaler configuration for the cluster
+     */
+    readonly autoScalerProfile?: AksClusterAutoScalerProfile;
+    /**
+     * The API server access configuration
+     */
+    readonly apiServerAccessProfile?: AksClusterApiServerAccessProfile;
+    /**
+     * The resource ID of the disk encryption set for encrypting disks
+     */
+    readonly diskEncryptionSetID?: string;
+    /**
+     * Whether to enable Kubernetes Role-Based Access Control
+     * @default true
+     */
+    readonly enableRBAC?: boolean;
+    /**
+     * The name of the resource group for cluster nodes
+     * If not specified, Azure will auto-generate the name
+     */
+    readonly nodeResourceGroup?: string;
+    /**
+     * The addon profiles for cluster addons
+     */
+    readonly addonProfiles?: AksClusterAddonProfiles;
+    /**
+     * The Linux profile for SSH access
+     */
+    readonly linuxProfile?: AksClusterLinuxProfile;
+    /**
+     * The Windows profile for Windows node pools
+     */
+    readonly windowsProfile?: AksClusterWindowsProfile;
+    /**
+     * The OIDC issuer profile for workload identity
+     */
+    readonly oidcIssuerProfile?: AksClusterOidcIssuerProfile;
+    /**
+     * The security profile for the cluster
+     */
+    readonly securityProfile?: AksClusterSecurityProfile;
+    /**
+     * The storage profile for CSI drivers
+     */
+    readonly storageProfile?: AksClusterStorageProfile;
+    /**
+     * The HTTP proxy configuration
+     */
+    readonly httpProxyConfig?: AksClusterHttpProxyConfig;
+    /**
+     * The workload auto-scaler profile
+     */
+    readonly workloadAutoScalerProfile?: AksClusterWorkloadAutoScalerProfile;
+    /**
+     * Whether to disable local accounts
+     * @default false
+     */
+    readonly disableLocalAccounts?: boolean;
+    /**
+     * Whether the cluster is accessible from the public internet
+     * @example "Enabled"
+     * @example "Disabled"
+     */
+    readonly publicNetworkAccess?: string;
+    /**
+     * The support plan for the cluster
+     * @example "KubernetesOfficial"
+     * @example "AKSLongTermSupport"
+     */
+    readonly supportPlan?: string;
+    /**
+     * The lifecycle rules to ignore changes
+     * Useful for properties that are externally managed or should not trigger updates
+     * @example ["kubernetesVersion", "agentPoolProfiles"]
+     */
+    readonly ignoreChanges?: string[];
+    /**
+     * Resource group ID where the AKS cluster will be created
+     */
+    readonly resourceGroupId?: string;
+}
+/**
+ * The resource body interface for Azure AKS API calls
+ */
+export interface AksClusterBody {
+    readonly location: string;
+    readonly tags?: {
+        [key: string]: string;
+    };
+    readonly sku?: AksClusterSku;
+    readonly identity?: AksClusterIdentity;
+    readonly properties: AksClusterBodyProperties;
+}
+/**
+ * AKS Cluster properties for the request body
+ */
+export interface AksClusterBodyProperties {
+    readonly kubernetesVersion?: string;
+    readonly dnsPrefix: string;
+    readonly fqdn?: string;
+    readonly privateFQDN?: string;
+    readonly agentPoolProfiles: AksClusterAgentPoolProfile[];
+    readonly servicePrincipalProfile?: AksClusterServicePrincipalProfile;
+    readonly networkProfile?: AksClusterNetworkProfile;
+    readonly aadProfile?: AksClusterAadProfile;
+    readonly autoScalerProfile?: AksClusterAutoScalerProfile;
+    readonly apiServerAccessProfile?: AksClusterApiServerAccessProfile;
+    readonly diskEncryptionSetID?: string;
+    readonly enableRBAC?: boolean;
+    readonly nodeResourceGroup?: string;
+    readonly addonProfiles?: AksClusterAddonProfiles;
+    readonly linuxProfile?: AksClusterLinuxProfile;
+    readonly windowsProfile?: AksClusterWindowsProfile;
+    readonly oidcIssuerProfile?: AksClusterOidcIssuerProfile;
+    readonly securityProfile?: AksClusterSecurityProfile;
+    readonly storageProfile?: AksClusterStorageProfile;
+    readonly httpProxyConfig?: AksClusterHttpProxyConfig;
+    readonly workloadAutoScalerProfile?: AksClusterWorkloadAutoScalerProfile;
+    readonly disableLocalAccounts?: boolean;
+    readonly publicNetworkAccess?: string;
+    readonly supportPlan?: string;
+}
+/**
+ * Unified Azure Kubernetes Service cluster implementation
+ *
+ * This class provides a single, version-aware implementation that automatically handles version
+ * resolution, schema validation, and property transformation while maintaining full JSII compliance.
+ *
+ * The class uses the VersionedAzapiResource framework to provide:
+ * - Automatic latest version resolution (2025-07-01 as of this implementation)
+ * - Support for explicit version pinning when stability is required
+ * - Schema-driven property validation and transformation
+ * - Migration analysis and deprecation warnings
+ * - Full JSII compliance for multi-language support
+ *
+ * @example
+ * // Basic AKS cluster with system node pool:
+ * const aksCluster = new AksCluster(this, "aks", {
+ *   name: "my-aks-cluster",
+ *   location: "eastus",
+ *   resourceGroupId: resourceGroup.id,
+ *   dnsPrefix: "myaks",
+ *   agentPoolProfiles: [{
+ *     name: "system",
+ *     count: 3,
+ *     vmSize: "Standard_D2s_v3",
+ *     mode: "System"
+ *   }],
+ *   identity: {
+ *     type: "SystemAssigned"
+ *   }
+ * });
+ *
+ * @example
+ * // AKS cluster with explicit version pinning and advanced networking:
+ * const aksCluster = new AksCluster(this, "aks", {
+ *   name: "my-aks-cluster",
+ *   location: "eastus",
+ *   resourceGroupId: resourceGroup.id,
+ *   apiVersion: "2025-07-01",
+ *   dnsPrefix: "myaks",
+ *   kubernetesVersion: "1.28.3",
+ *   agentPoolProfiles: [{
+ *     name: "system",
+ *     count: 3,
+ *     vmSize: "Standard_D2s_v3",
+ *     mode: "System",
+ *     vnetSubnetID: subnet.id
+ *   }],
+ *   identity: {
+ *     type: "SystemAssigned"
+ *   },
+ *   networkProfile: {
+ *     networkPlugin: "azure",
+ *     serviceCidr: "10.0.0.0/16",
+ *     dnsServiceIP: "10.0.0.10"
+ *   },
+ *   enableRBAC: true
+ * });
+ *
+ * @stability stable
+ */
+export declare class AksCluster extends AzapiResource {
+    /**
+     * Returns a production-ready monitoring configuration for AKS Clusters
+     *
+     * This static factory method provides a complete MonitoringConfig with sensible defaults
+     * for AKS monitoring including node CPU, node memory, failed pod alerts, and deletion tracking.
+     *
+     * @param actionGroupId - The resource ID of the action group for alert notifications
+     * @param workspaceId - Optional Log Analytics workspace ID for diagnostic settings
+     * @param options - Optional configuration to customize thresholds and enable/disable specific alerts
+     * @returns A complete MonitoringConfig object ready to use in AksCluster props
+     *
+     * @example
+     * // Basic usage with all defaults
+     * const aksCluster = new AksCluster(this, "aks", {
+     *   // ... other properties ...
+     *   monitoring: AksCluster.defaultMonitoring(actionGroup.id, workspace.id)
+     * });
+     *
+     * @example
+     * // Custom thresholds and severities
+     * const aksCluster = new AksCluster(this, "aks", {
+     *   // ... other properties ...
+     *   monitoring: AksCluster.defaultMonitoring(
+     *     actionGroup.id,
+     *     workspace.id,
+     *     {
+     *       nodeCpuThreshold: 90,
+     *       nodeMemoryThreshold: 90,
+     *       enableFailedPodAlert: false
+     *     }
+     *   )
+     * });
+     *
+     * @stability stable
+     */
+    static defaultMonitoring(actionGroupId: string, workspaceId?: string, options?: AksClusterMonitoringOptions): MonitoringConfig;
+    /**
+     * Static initialization flag to ensure schemas are registered only once
+     */
+    private static schemasRegistered;
+    /**
+     * Ensures that AKS Cluster schemas are registered with the ApiVersionManager
+     * This is called once during the first AksCluster instantiation
+     */
+    private static ensureSchemasRegistered;
+    /**
+     * The input properties for this AKS Cluster instance
+     */
+    readonly props: AksClusterProps;
+    readonly idOutput: cdktf.TerraformOutput;
+    readonly locationOutput: cdktf.TerraformOutput;
+    readonly nameOutput: cdktf.TerraformOutput;
+    readonly tagsOutput: cdktf.TerraformOutput;
+    readonly fqdnOutput: cdktf.TerraformOutput;
+    readonly id: string;
+    readonly tags: {
+        [key: string]: string;
+    };
+    private readonly credentialAction;
+    /**
+     * Creates a new Azure Kubernetes Service cluster using the VersionedAzapiResource framework
+     *
+     * The constructor automatically handles version resolution, schema registration,
+     * validation, and resource creation.
+     *
+     * @param scope - The scope in which to define this construct
+     * @param id - The unique identifier for this instance
+     * @param props - Configuration properties for the AKS cluster
+     */
+    constructor(scope: Construct, id: string, props: AksClusterProps);
+    /**
+     * Gets the default API version to use when no explicit version is specified
+     * Returns the most recent stable version as the default
+     */
+    protected defaultVersion(): string;
+    /**
+     * Gets the Azure resource type for AKS Clusters
+     */
+    protected resourceType(): string;
+    /**
+     * Gets the API schema for the resolved version
+     * Uses the framework's schema resolution to get the appropriate schema
+     */
+    protected apiSchema(): ApiSchema;
+    /**
+     * Creates the resource body for the Azure API call
+     * Transforms the input properties into the JSON format expected by Azure REST API
+     */
+    protected createResourceBody(props: any): any;
+    /**
+     * Get the FQDN of the cluster
+     */
+    get fqdn(): string;
+    /**
+     * Get the private FQDN of the cluster (if private cluster is enabled)
+     */
+    get privateFqdn(): string;
+    /**
+     * Get the Kubernetes configuration for the cluster
+     *
+     * This retrieves the cluster admin credentials using an azapi_resource_action.
+     * The kubeConfig is base64 encoded and contains the full kubectl configuration.
+     */
+    get kubeConfig(): string;
+    /**
+     * Get the current Kubernetes version running on the cluster
+     */
+    get currentKubernetesVersion(): string;
+    /**
+     * Get the node resource group name
+     */
+    get nodeResourceGroupName(): string;
+    /**
+     * Add a tag to the AKS Cluster
+     * Note: This modifies the construct props but requires a new deployment to take effect
+     */
+    addTag(key: string, value: string): void;
+    /**
+     * Remove a tag from the AKS Cluster
+     * Note: This modifies the construct props but requires a new deployment to take effect
+     */
+    removeTag(key: string): void;
+    /**
+     * Transforms autoScalerProfile properties from camelCase to kebab-case
+     * The Azure AKS API requires kebab-case for autoScalerProfile properties
+     */
+    private _transformAutoScalerProfile;
+    /**
+     * Applies ignore changes lifecycle rules if specified in props
+     */
+    private _applyIgnoreChanges;
+}