Add AKS persistent volume support

[Mitch Denny (mitchdenny)]

Description

AKS users could use Kubernetes persistent volumes only by reaching through to the underlying Kubernetes integration. This change exposes AddPersistentVolume directly on AzureKubernetesEnvironmentResource, so workloads targeting AKS can configure and mount persistent storage through the AKS API.

The new API forwards to the AKS environment's existing Kubernetes publisher. When no storage class is specified, the generated claim uses the cluster default; standard AKS clusters dynamically provision an Azure managed disk. Azure Files-specific APIs are intentionally deferred until managed-identity mounting can be modeled securely.

User-facing usage

C# AppHost:

var aks = builder.AddAzureKubernetesEnvironment("aks");

var data = aks.AddPersistentVolume("data")
    .WithCapacity("20Gi");

builder.AddProject<Projects.Api>("api")
    .WithPersistentVolume(data, "/data");

TypeScript AppHost:

const aks = await builder.addAzureKubernetesEnvironment("aks");
const data = await aks.addPersistentVolume("data");
await data.withCapacity("20Gi");

await api.withKubernetesPersistentVolumeMount(data, "/data");

The change also adds:

• publish-output coverage for the AKS forwarding API and default StorageClass behavior;
• TypeScript and Java SDK-generation fixtures;
• an Azure deployment E2E test that writes through a port-forwarded API, redeploys the workload, verifies the pod changed while the PVC identity remained stable, and reads the persisted value.

Validation:

• dotnet test --project tests/Aspire.Hosting.Azure.Kubernetes.Tests/Aspire.Hosting.Azure.Kubernetes.Tests.csproj --no-launch-profile -- --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true" — 69 passed.
• dotnet build tests/Aspire.Deployment.EndToEnd.Tests/Aspire.Deployment.EndToEnd.Tests.csproj --no-restore — succeeded.
• Generated TypeScript SDK validation succeeded with the source-built Aspire CLI.
• The live Azure deployment test was not run locally because no deployment-test subscription was configured.

Fixes #19210

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 19226

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 19226"

[Copilot]

Pull request overview

Adds first-class persistent-volume support for AKS environments.

Changes:

• Adds the AKS AddPersistentVolume forwarding API.
• Adds C#, TypeScript, Java, snapshot, and Azure deployment coverage.
• Documents AKS persistent-volume usage and defaults.

Show a summary per file

File	Description
src/Aspire.Hosting.Azure.Kubernetes/AzureKubernetesPersistentVolumeExtensions.cs	Adds the forwarding API.
src/Aspire.Hosting.Azure.Kubernetes/Aspire.Hosting.Azure.Kubernetes.csproj	Enables integration analyzers.
src/Aspire.Hosting.Azure.Kubernetes/README.md	Documents persistent volumes.
tests/Aspire.Hosting.Azure.Kubernetes.Tests/AzureKubernetesPersistentVolumeTests.cs	Tests parentage and generated claims.
tests/Aspire.Hosting.Azure.Kubernetes.Tests/Snapshots/AzureKubernetesPersistentVolumeTests.AksAddPersistentVolume_GeneratesClaimUsingClusterDefaults.verified.yaml	Verifies default claim output.
tests/Aspire.Deployment.EndToEnd.Tests/AksPersistentVolumeDeploymentTests.cs	Verifies persistence across AKS redeployment.
tests/PolyglotAppHosts/Aspire.Hosting/TypeScript/apphost.mts	Exercises TypeScript bindings.
tests/PolyglotAppHosts/Aspire.Hosting/Java/AppHost.java	Exercises Java bindings.

Review details

Tip

Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 8/8 changed files
• Comments generated: 0
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

🚀 Deployment tests starting on PR #19226...

This will deploy to real Azure infrastructure. Results will be posted here when complete.

View workflow run

[github-actions]

🚀 Deployment tests starting on PR #19226...

This will deploy to real Azure infrastructure. Results will be posted here when complete.

View workflow run

[James Newton-King (JamesNK)]

I haven't tested this myself. I trust that this has been tested end to end. The dedicated deployment E2E job is still running at the time of this approval.

[James Newton-King (JamesNK)]

Found one additional blocking issue in the AKS deployment scenario: the default non-root .NET container cannot write to the fresh managed-disk mount without a pod fsGroup. Local publish proof confirmed the generated mount has no security context and the SDK image runs as UID 1654. The existing cleanup thread remains separate.

[github-actions]

🚀 Deployment tests starting on PR #19226...

This will deploy to real Azure infrastructure. Results will be posted here when complete.

View workflow run

[Copilot]

Review details

Suppressed comments (1)

tests/Aspire.Deployment.EndToEnd.Tests/AksPersistentVolumeDeploymentTests.cs:112

• This writes the ephemeral AKS credentials into the caller's default ~/.kube/config and switches its current context. A local test run can therefore leave the developer pointed at a cluster that the finally block deletes. Export a workspace-local KUBECONFIG before calling az aks get-credentials, as the isolated deployment tests do.

                $"az aks get-credentials --resource-group {resourceGroupName} --name \"$AKS_NAME\" --overwrite-existing",

• Files reviewed: 8/8 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

🚀 Deployment tests starting on PR #19226...

This will deploy to real Azure infrastructure. Results will be posted here when complete.

View workflow run

[Copilot]

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (1)

tests/Aspire.Deployment.EndToEnd.Tests/AksPersistentVolumeDeploymentTests.cs:47

• Dispose the temporary workspace so its generated project and build artifacts are deleted after the deployment test. As written, every local run leaves the entire workspace behind.

        var workspace = TemporaryWorkspace.Create(output);

• Files reviewed: 8/8 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Tests selector (audit mode)

The full test matrix and all jobs still run in audit mode. The tests and jobs below are what selective CI would run under enforcement.

3 / 100 test projects · 4 jobs, from 7 changed files.

Selected test projects (3 / 100)

Aspire.Deployment.EndToEnd.Tests, Aspire.Hosting.Azure.Kubernetes.Tests, Aspire.Hosting.Azure.Tests

Selected jobs (4)

deployment-e2e, extension-e2e, polyglot, typescript-api-compat

---

How these were chosen — grouped by what changed

🔧 src/Aspire.Hosting.Azure.Kubernetes/Aspire.Hosting.Azure.Kubernetes.csproj (changed source)
→ 2 directly: Aspire.Hosting.Azure.Kubernetes.Tests, Aspire.Hosting.Azure.Tests

🔧 src/Aspire.Hosting.Azure.Kubernetes/AzureKubernetesPersistentVolumeExtensions.cs (changed source)
→ 2 directly: Aspire.Hosting.Azure.Kubernetes.Tests, Aspire.Hosting.Azure.Tests

🧪 tests/Aspire.Deployment.EndToEnd.Tests/AksPersistentVolumeDeploymentTests.cs (changed test)
→ 1 directly: Aspire.Deployment.EndToEnd.Tests

🧪 tests/Aspire.Hosting.Azure.Kubernetes.Tests/AzureKubernetesPersistentVolumeTests.cs (changed test)
→ 1 directly: Aspire.Hosting.Azure.Kubernetes.Tests

🧪 tests/Aspire.Hosting.Azure.Kubernetes.Tests/Snapshots/AzureKubernetesPersistentVolumeTests.AksAddPersistentVolume_GeneratesClaimUsingClusterDefaults.verified.yaml (changed test)
→ 1 directly: Aspire.Hosting.Azure.Kubernetes.Tests

Job reasons

Job	Triggered by
deployment-e2e	• tests/Aspire.Deployment.EndToEnd.Tests/AksPersistentVolumeDeploymentTests.cs • affected project Aspire.Hosting.Azure.Kubernetes
extension-e2e	• src/Aspire.Hosting.Azure.Kubernetes/Aspire.Hosting.Azure.Kubernetes.csproj, src/Aspire.Hosting.Azure.Kubernetes/AzureKubernetesPersistentVolumeExtensions.cs • affected project Aspire.Hosting.Azure.Kubernetes
polyglot	tests/PolyglotAppHosts/Aspire.Hosting/Java/AppHost.java, tests/PolyglotAppHosts/Aspire.Hosting/TypeScript/apphost.mts
typescript-api-compat	affected project Aspire.Hosting.Azure.Kubernetes

---

Selection computed for commit a5da9c6.

[Copilot]

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Mitch Denny (mitchdenny)]

/backport to release/13.5

[github-actions]

Started backporting to release/13.5 (link to workflow run)

[aspire-repo-bot]

Pull request created: #1474

Generated by PR Documentation Check · auto · 101.8 AIC · ⌖ 13.2 AIC · ⊞ 19.6K

[aspire-repo-bot]

📝 Documentation has been drafted in microsoft/aspire.dev#1474 targeting release/13.5.

Added an "Add a persistent volume" section to the AKS integration page (integrations/cloud/azure/aks/index.mdx) covering the new AddPersistentVolume/addPersistentVolume AKS API, the ASPIRECOMPUTE002 experimental note, default storage-class behavior, and deferred Azure Files support. Cross-linked with deployment/kubernetes/persistent-volumes.mdx, which gained a short "Persistent volumes on AKS" pointer section. Both files were edited in place — no new pages.

Note

This draft PR needs human review before merging.

[github-actions]

⚠️ CI Failure Analysis: Possible Flaky Test(s)

The CI build failed due to test failure(s) that appear unrelated to the PR changes. These may be flaky tests.

Suspected flaky test(s):

• extension/src/test/e2eShardMatrix.test.js (Extension host E2E test) in job Tests / Run VS Code extension unit tests (Windows)
  • Error: 1 test failed. Extension host test runner error 1 test failed.
  • Stack Trace (first frames):

    at Context.<anonymous> (d:\a\aspire\aspire\extension\out\test\e2eShardMatrix.test.js:146:9)
    	at process.processImmediate (node:internal/timers:504:21)
    Exit code: 1
    

  • Why likely flaky: This test is not related to any file changed by the PR (which only modifies Aspire.Hosting.Azure.Kubernetes and its tests). The error signature matches a previously recorded recurring flaky failure for this exact test on Windows Extension host test runner.

Suggested actions:

• Re-run the failed CI jobs to confirm if the failure is intermittent
• If the test continues to fail, consider quarantining it using /quarantine-test <test name> <issue URL>
• Search existing issues to see if this test is already known to be flaky

You can re-run the failed jobs from the workflow run page.