[docs] Document AddPersistentVolume on AKS environments

[aspire-repo-bot]

Documents changes from microsoft/aspire#19226

@mitchdenny

Targeting release/13.5 — the latest release branch on microsoft/aspire.dev — because release/13.6 (from the source PR milestone 13.6) does not exist there.

Why

microsoft/aspire#19226 adds AddPersistentVolume directly to AzureKubernetesEnvironmentResource, so AKS users no longer need to reach through to the underlying Kubernetes integration to model persistent storage. This is a new public API (AzureKubernetesPersistentVolumeExtensions, marked [Experimental("ASPIRECOMPUTE002")]), and the source PR's own README update shows the intended AKS usage pattern — none of that was previously documented on aspire.dev.

What changed

• src/frontend/src/content/docs/integrations/cloud/azure/aks/index.mdx: added a new "Add a persistent volume" section showing the AKS-specific AddPersistentVolume/addPersistentVolume call (C# and TypeScript), the experimental-diagnostic note, default storage-class behavior, and a note that Azure Files-specific APIs are deferred. Added a cross-link to the generic Kubernetes persistent-volumes page (for the full configuration/binding API surface) and updated the "See also" list.
• src/frontend/src/content/docs/deployment/kubernetes/persistent-volumes.mdx: added a short "Persistent volumes on AKS" section pointing back to the new AKS-specific entry point, and linked the AKS integration page from "See also".

Both pages were updated in place; no new pages were created.

Generated by PR Documentation Check for #19226 · auto · 101.8 AIC · ⌖ 13.2 AIC · ⊞ 19.6K · ◷

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1474. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.

[Alistair Matthews (alistairmatthews)]

Just a couple of small suggested changes.

[Alistair Matthews (alistairmatthews)]

I really think separate sentences are clearer here:

Suggested change

	When you don't set a storage class, the generated claim omits `spec.storageClassName` so the cluster's default storage class provisions the disk. A standard AKS cluster dynamically provisions an Azure managed disk for such claims — to request Premium SSD storage explicitly, call `WithStorageClass("managed-csi-premium")` in C# or `withStorageClass('managed-csi-premium')` in TypeScript.
	When you don't set a storage class, the generated claim omits `spec.storageClassName` so the cluster's default storage class provisions the disk. A standard AKS cluster dynamically provisions an Azure managed disk for such claims. To request Premium SSD storage explicitly, call `WithStorageClass("managed-csi-premium")` in C# or `withStorageClass('managed-csi-premium')` in TypeScript.

[Alistair Matthews (alistairmatthews)]

I think this is a little strangely worded. How about:

Suggested change

	Azure Files-specific APIs are intentionally deferred until managed-identity mounting can be modeled securely.
	The APIs that are specific to Azure Files are intentionally deferred until managed-identity mounting can be modeled securely.

[Copilot]

Pull request overview

Documents the new AKS-specific AddPersistentVolume entry point so AKS users can model durable storage directly on AzureKubernetesEnvironmentResource, while cross-linking to the existing Kubernetes persistent volume documentation for the full configuration/binding API surface.

Changes:

• Added an “Add a persistent volume” section to the AKS integration docs with C#/TypeScript examples and guidance on default storage class behavior.
• Added a short “Persistent volumes on AKS” section to the Kubernetes persistent volumes page pointing back to the AKS integration docs.
• Updated “See also” links on both pages to connect the AKS and Kubernetes persistent-volume documentation.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/frontend/src/content/docs/integrations/cloud/azure/aks/index.mdx	Adds AKS-specific persistent-volume guidance and examples, with links back to the generic Kubernetes PV docs.
src/frontend/src/content/docs/deployment/kubernetes/persistent-volumes.mdx	Adds an AKS callout section and cross-links to the AKS integration page.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[David Pine (IEvangelist)]

Docs-accuracy review — automated (Phase A: claims vs. source · Phase B: doc-tester)

Phase A source of truth: microsoft/aspire @ release/13.5 · SHA 8ab6999850d96e0023670799edbd4bdc245ad63c (PR targets release/13.5; documents microsoft/aspire#19226).
Claims extracted: 8 non-narrative (+1 narrative) → verified: 7 · verified-with-nuance: 1 · unverifiable: 0 · contradicted: 0
Phase B (doc-tester): 2 pages exercised (/deployment/kubernetes/persistent-volumes/, /integrations/cloud/azure/aks/) · 0 critical · 2 warnings · 2 knowledge gaps.

Verdict: COMMENT. This is a high-fidelity PR — the C# sample and the storage-class prose mirror the source's own XML-doc <example> almost verbatim, and the non-obvious TypeScript name withKubernetesPersistentVolumeMount is correct. Nothing blocks merge. Worth a look: one Phase A nuance (the managed-csi-premium storage-class value is external AKS knowledge) and two Phase B new-user warnings (how to suppress ASPIRECOMPUTE002; the TypeScript snippet's implicit api variable).

---

Phase A — Claim verification

Every non-narrative claim was located in microsoft/aspire @ release/13.5. No contradicted or unverifiable claims → no inline blocking comments. One verified-with-nuance claim (P8) is highlighted.

⚠️ Nuance worth a look — Claim P8 (aks/index.mdx, "Add a persistent volume")

to request Premium SSD storage explicitly, call WithStorageClass("managed-csi-premium") in C# or withStorageClass('managed-csi-premium') in TypeScript.

API verified, value is external. WithStorageClass(...) exists (src/Aspire.Hosting.Kubernetes/KubernetesPersistentVolumeExtensions.cs:74,95) and exports to TypeScript as withStorageClass. Nuance: the string managed-csi-premium is an AKS-provided storage-class name, not defined anywhere in microsoft/aspire, so that specific value can't be verified from Aspire source (it is a real AKS Premium SSD class). Accurate as written — flagged only for transparency.

✅ Verified claims (7 verified + 1 verified-with-nuance, +1 narrative) — evidence

Evidence paths are in microsoft/aspire @ 8ab6999850d96e0023670799edbd4bdc245ad63c.

deployment/kubernetes/persistent-volumes.mdx — "Persistent volumes on AKS"

• P1 (api-shape) — AddPersistentVolume is available directly on an AKS environment. verified — public static IResourceBuilder<KubernetesPersistentVolumeResource> AddPersistentVolume(this IResourceBuilder<AzureKubernetesEnvironmentResource> builder, ...) (src/Aspire.Hosting.Azure.Kubernetes/AzureKubernetesPersistentVolumeExtensions.cs:53).
• P2 (api-behavior) — the AKS overload forwards to the same publisher and reuses the same configuration/binding APIs. verified — it resolves builder.Resource.KubernetesEnvironment and returns k8sEnvBuilder.AddPersistentVolume(name) (same file, lines 59-61), so the Aspire.Hosting.Kubernetes WithCapacity/WithStorageClass/WithPersistentVolume apply.

integrations/cloud/azure/aks/index.mdx — "Add a persistent volume"

• P3 (config / diagnostic) — the APIs are experimental; in C# suppress ASPIRECOMPUTE002. verified — [Experimental("ASPIRECOMPUTE002", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")] on the AKS PV extensions class (AzureKubernetesPersistentVolumeExtensions.cs:15).
• P4 (api-shape, C# sample) — AddAzureKubernetesEnvironment("aks") → AddPersistentVolume("data").WithCapacity("20Gi") → WithPersistentVolume(data, "/data"). verified — matches the source's own <example> verbatim; APIs at AzureKubernetesEnvironmentExtensions.cs:50, AzureKubernetesPersistentVolumeExtensions.cs:53, KubernetesPersistentVolumeExtensions.cs:116/136 (WithCapacity), :253/293 (WithPersistentVolume).
• P5 (api-shape, TypeScript sample) — addAzureKubernetesEnvironment, addPersistentVolume, withCapacity, withKubernetesPersistentVolumeMount. verified — [AspireExport] on AddAzureKubernetesEnvironment → addAzureKubernetesEnvironment (AzureKubernetesEnvironmentExtensions.cs:49); [AspireExport("withKubernetesPersistentVolumeMount")] on the mount overload (KubernetesPersistentVolumeExtensions.cs:292); withCapacity is the default export (:115). The same TS surface appears in src/Aspire.Hosting.Azure.Kubernetes/README.md:63 and in tests/Aspire.Cli.EndToEnd.Tests/KubernetesDeployTypeScriptWithPersistentVolumeTests.cs:13.
• P6 (api-behavior) — with no storage class set, the generated claim omits spec.storageClassName so the cluster's default storage class is used. verified — the PVC builder sets claim.Spec.StorageClassName only when the volume's StorageClassName or the environment's DefaultStorageClassName is set, otherwise leaves it unset (KubernetesEnvironmentResource.cs:968-978); also documented in the API's own remarks (AzureKubernetesPersistentVolumeExtensions.cs:32-34).
• P7 (api-behavior) — "A standard AKS cluster dynamically provisions an Azure managed disk for such claims." verified — matches the source's XML-doc remarks verbatim (AzureKubernetesPersistentVolumeExtensions.cs:34).
• P8 (api-shape) — WithStorageClass("managed-csi-premium") / withStorageClass('managed-csi-premium'). verified-with-nuance — see note above.
• P9 (narrative) — "Azure Files-specific APIs are intentionally deferred until managed-identity mounting can be modeled securely." Roadmap statement; noted, not blocking.

---

Phase B — Doc-tester results (blind new-user perspective, no source code consulted)

Served the PR head (0a92ed8b194a295b6a792567d6d118bb50a62996) locally via pnpm dev at http://localhost:4321/ and navigated with Playwright. Report reproduced verbatim:

Documentation Test Report

Focus Area: PR #1474 persistent volume additions for AKS documentation
Date: 2026-08-14
Tester: doc-tester agent
Served Base URL: http://localhost:4321/
Served Head SHA: 0a92ed8b194a295b6a792567d6d118bb50a62996

Routes Exercised:

• http://localhost:4321/deployment/kubernetes/persistent-volumes/
• http://localhost:4321/deployment/kubernetes/persistent-volumes/#persistent-volumes-on-aks
• http://localhost:4321/integrations/cloud/azure/aks/
• http://localhost:4321/integrations/cloud/azure/aks/#add-a-persistent-volume
• http://localhost:4321/integrations/cloud/azure/aks/?aspire-lang=typescript#add-a-persistent-volume

Summary

Category	Passed	Failed	Warnings
Content Accuracy	4	0	1
Code Examples	2	0	1
CLI Commands	0	0	0
Links	4	0	0

Critical Issues

None.

Warnings

Warning 1: Experimental diagnostic suppression is mentioned but not shown

Location: .../integrations/cloud/azure/aks/#add-a-persistent-volume
Issue: The note says: "Persistent volume APIs are experimental. In C#, suppress the ASPIRECOMPUTE002 diagnostic to use them." A new user is told what to suppress, but not how to suppress it.
Suggestion: Add a short suppression example or link to guidance for suppressing Aspire diagnostics.

Warning 2: TypeScript persistent volume example relies on an implicit api variable

Location: .../integrations/cloud/azure/aks/?aspire-lang=typescript#add-a-persistent-volume
Issue: The TypeScript tab shows await api.withKubernetesPersistentVolumeMount(data, "/data");, but the api variable is not defined in that section's code block. A previous page section defines an api, but readers landing directly on the anchor may not know that dependency.
Suggestion: Either define api in the TypeScript snippet or add "assuming api is the app resource defined earlier" before the code block.

Passed Checks

• The PR head loaded locally at http://localhost:4321/.
• The persistent volumes page loaded successfully.
• The "Persistent volumes on AKS" section appears in the "On this page" navigation.
• Clicking "Persistent volumes on AKS" navigated to #persistent-volumes-on-aks.
• The persistent volumes page links to /integrations/cloud/azure/aks/#add-a-persistent-volume, and the link resolved correctly.
• The persistent volumes page "See also" link to the AKS integration page resolved correctly.
• The AKS integration page loaded successfully.
• The "Add a persistent volume" section appears in the "On this page" navigation.
• Clicking "Add a persistent volume" navigated to #add-a-persistent-volume.
• The C# tab rendered the AKS AddPersistentVolume example.
• The TypeScript tab switched successfully and rendered the TypeScript example.
• The tab sync behavior worked: switching to TypeScript updated other synced code tabs and added ?aspire-lang=typescript.
• The storage class guidance for WithStorageClass("managed-csi-premium") / withStorageClass('managed-csi-premium') is visible and understandable.
• The Azure Files deferral note is visible and understandable.
• AKS page links back to /deployment/kubernetes/persistent-volumes/, and the link resolved correctly.

Recommendations

1. Priority fixes: No critical issues found.
2. Documentation gaps: Add concrete guidance for suppressing ASPIRECOMPUTE002; make the TypeScript snippet self-contained or explicitly reference the earlier api variable.
3. Product issues: None discovered from blind documentation testing.

Knowledge Gaps

Knowledge Gap: Suppressing ASPIRECOMPUTE002

What I needed to know: How a C# Aspire user suppresses the ASPIRECOMPUTE002 diagnostic.
Source of my knowledge: Prior C# knowledge, not explained in this section.
User impact: New users may understand that suppression is required but not know the syntax or preferred location.

Knowledge Gap: TypeScript api variable context

What I needed to know: Whether api in the TypeScript persistent volume snippet is expected to come from the earlier "Add AKS environment" example.
Source of my knowledge: Inference from earlier page content.
User impact: Readers arriving directly at the section may copy incomplete code.

---

_{Automated docs-accuracy review. Phase A reads microsoft/aspire source (read-only); Phase B runs the doc-tester skill blind to source code against a local render of this PR.}