{"record":{"id":"dd77595230284207","repo":"microsoft/aspire","slug":"timed-out-waiting-for-the-azure-alb-external-gatewayclass-to","errorCode":null,"errorMessage":"Timed out waiting for the 'azure-alb-external' GatewayClass to appear in the cluster. Ensure the AKS preview features 'Microsoft.ContainerService/AKSGatewayAPIPreview' and 'Microsoft.ContainerService/AKSAppGatewayContainersPreview' are registered on the subscription, and that the AGC ALB controller add-on (ingressProfile.applicationLoadBalancer) finished installing.","messagePattern":"Timed out waiting for the 'azure-alb-external' GatewayClass to appear in the cluster\\. Ensure the AKS preview features 'Microsoft\\.ContainerService/AKSGatewayAPIPreview' and 'Microsoft\\.ContainerService/AKSAppGatewayContainersPreview' are registered on the subscription, and that the AGC ALB controller add-on \\(ingressProfile\\.applicationLoadBalancer\\) finished installing\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Azure.Kubernetes/AzureKubernetesEnvironmentResource.AksPipeline.cs","lineNumber":715,"sourceCode":"\n            int exitCode;\n            await using (disposable.ConfigureAwait(false))\n            {\n                var result = await resultTask.WaitAsync(cancellationToken).ConfigureAwait(false);\n                exitCode = result.ExitCode;\n            }\n\n            if (exitCode == 0)\n            {\n                logger.LogInformation(\n                    \"GatewayClass 'azure-alb-external' is available (after {Attempts} probe(s))\",\n                    attempt);\n                return;\n            }\n\n            if (DateTime.UtcNow >= deadline)\n            {\n                throw new InvalidOperationException(\n                    \"Timed out waiting for the 'azure-alb-external' GatewayClass to appear in the cluster. \" +\n                    \"Ensure the AKS preview features 'Microsoft.ContainerService/AKSGatewayAPIPreview' and \" +\n                    \"'Microsoft.ContainerService/AKSAppGatewayContainersPreview' are registered on the subscription, \" +\n                    \"and that the AGC ALB controller add-on (ingressProfile.applicationLoadBalancer) finished installing.\");\n            }\n\n            logger.LogDebug(\n                \"GatewayClass 'azure-alb-external' not yet available (attempt {Attempt}); retrying in {Delay}s\",\n                attempt, pollInterval.TotalSeconds);\n\n            await Task.Delay(pollInterval, cancellationToken).ConfigureAwait(false);\n        }\n    }\n\n    private static string FindAzCli()\n    {\n        var azPath = PathLookupHelper.FindFullPathFromPath(\"az\");\n        if (azPath is null)","sourceCodeStart":697,"sourceCodeEnd":733,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Azure.Kubernetes/AzureKubernetesEnvironmentResource.AksPipeline.cs#L697-L733","documentation":"The library polls for up to 10 minutes for the 'azure-alb-external' GatewayClass to appear in the AKS cluster after provisioning, and it never showed up. This GatewayClass is installed asynchronously by the AGC ALB controller add-on, and its absence means the required AKS preview features or the add-on did not activate.","triggerScenarios":"WaitForAzureAlbGatewayClassAsync polls 'kubectl get gatewayclass' until the deadline passes without seeing azure-alb-external, then throws.","commonSituations":"AKS preview features AKSGatewayAPIPreview / AKSAppGatewayContainersPreview not registered on the subscription; cluster created without ingressProfile.applicationLoadBalancer; slow add-on rollout exceeding 10 minutes; cluster in a failed provisioning state.","solutions":["Register the preview features and reinstall the extension:\n  az feature register --namespace Microsoft.ContainerService --name AKSGatewayAPIPreview\n  az feature register --namespace Microsoft.ContainerService --name AKSAppGatewayContainersPreview\n  az provider register --namespace Microsoft.ContainerService","Verify the cluster was created with ingressProfile.applicationLoadBalancer enabled; otherwise recreate it with the AGC add-on","Check add-on status: kubectl get pods -n azure-alb-system and az aks show to confirm provisioning state Succeeded","Wait and retry — a slow rollout can exceed the 10-minute budget; re-running the deploy resumes polling"],"exampleFix":"// before\n// az feature list -o table | grep AKSGatewayAPIPreview   # NotRegistered\n// after\n// az feature register --namespace Microsoft.ContainerService --name AKSGatewayAPIPreview\n// az feature register --namespace Microsoft.ContainerService --name AKSAppGatewayContainersPreview\n// az provider register --namespace Microsoft.ContainerService","handlingStrategy":"retry","validationCode":"var classOutput = await RunKubectlAsync(\"get gatewayclass azure-alb-external -o name\");\nif (string.IsNullOrWhiteSpace(classOutput))\n    Console.WriteLine(\"azure-alb-external GatewayClass not present yet; check preview features and add-on.\");","typeGuard":null,"tryCatchPattern":"catch (InvalidOperationException ex) when (ex.Message.Contains(\"azure-alb-external\"))\n{\n    // register AKSGatewayAPIPreview and AKSAppGatewayContainersPreview, then redeploy\n}","preventionTips":["Register both AKS preview features before first deploy","Create the cluster with ingressProfile.applicationLoadBalancer enabled","Allow >10 minutes for the add-on; rerun the deploy rather than tearing down"],"tags":["azure","aks","agc","gateway-api","timeout","preview-features"],"backgroundTag":"request-timeout","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}