[docs] Document AddPersistentVolume on AKS environments - #1474
[docs] Document AddPersistentVolume on AKS environments#1474aspire-repo-bot[bot] wants to merge 1 commit into
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
aspire-repo-bot
Bot
added
the
docs-from-code
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
Alistair Matthews (alistairmatthews)
left a comment
Alistair Matthews (alistairmatthews)
left a comment
There was a problem hiding this comment.
Just a couple of small suggested changes.
| </TabItem> | ||
| </Tabs> | ||
|
|
||
| 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. |
There was a problem hiding this comment.
I really think separate sentences are clearer here:
| 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. |
| 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. | ||
|
|
||
| <Aside type="note"> | ||
| Azure Files-specific APIs are intentionally deferred until managed-identity mounting can be modeled securely. |
There was a problem hiding this comment.
I think this is a little strangely worded. How about:
| 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. |
There was a problem hiding this comment.
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.
| const aks = await builder.addAzureKubernetesEnvironment("aks"); | ||
|
|
||
| const data = await aks.addPersistentVolume("data"); | ||
| await data.withCapacity("20Gi"); | ||
|
|
||
| await api.withKubernetesPersistentVolumeMount(data, "/data"); |
David Pine (IEvangelist)
left a comment
David Pine (IEvangelist)
left a comment
There was a problem hiding this comment.
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# orwithStorageClass('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) —
AddPersistentVolumeis 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.KubernetesEnvironmentand returnsk8sEnvBuilder.AddPersistentVolume(name)(same file, lines 59-61), so theAspire.Hosting.KubernetesWithCapacity/WithStorageClass/WithPersistentVolumeapply.
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 atAzureKubernetesEnvironmentExtensions.cs:50,AzureKubernetesPersistentVolumeExtensions.cs:53,KubernetesPersistentVolumeExtensions.cs:116/136(WithCapacity),:253/293(WithPersistentVolume). - P5 (api-shape, TypeScript sample) —
addAzureKubernetesEnvironment,addPersistentVolume,withCapacity,withKubernetesPersistentVolumeMount. verified —[AspireExport]onAddAzureKubernetesEnvironment→addAzureKubernetesEnvironment(AzureKubernetesEnvironmentExtensions.cs:49);[AspireExport("withKubernetesPersistentVolumeMount")]on the mount overload (KubernetesPersistentVolumeExtensions.cs:292);withCapacityis the default export (:115). The same TS surface appears insrc/Aspire.Hosting.Azure.Kubernetes/README.md:63and intests/Aspire.Cli.EndToEnd.Tests/KubernetesDeployTypeScriptWithPersistentVolumeTests.cs:13. - P6 (api-behavior) — with no storage class set, the generated claim omits
spec.storageClassNameso the cluster's default storage class is used. verified — the PVC builder setsclaim.Spec.StorageClassNameonly when the volume'sStorageClassNameor the environment'sDefaultStorageClassNameis 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:0a92ed8b194a295b6a792567d6d118bb50a62996Routes Exercised:
http://localhost:4321/deployment/kubernetes/persistent-volumes/http://localhost:4321/deployment/kubernetes/persistent-volumes/#persistent-volumes-on-akshttp://localhost:4321/integrations/cloud/azure/aks/http://localhost:4321/integrations/cloud/azure/aks/#add-a-persistent-volumehttp://localhost:4321/integrations/cloud/azure/aks/?aspire-lang=typescript#add-a-persistent-volumeSummary
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 theASPIRECOMPUTE002diagnostic 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
apivariableLocation:
.../integrations/cloud/azure/aks/?aspire-lang=typescript#add-a-persistent-volume
Issue: The TypeScript tab showsawait api.withKubernetesPersistentVolumeMount(data, "/data");, but theapivariable is not defined in that section's code block. A previous page section defines anapi, but readers landing directly on the anchor may not know that dependency.
Suggestion: Either defineapiin the TypeScript snippet or add "assumingapiis 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
AddPersistentVolumeexample.- 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
- Priority fixes: No critical issues found.
- Documentation gaps: Add concrete guidance for suppressing
ASPIRECOMPUTE002; make the TypeScript snippet self-contained or explicitly reference the earlierapivariable.- Product issues: None discovered from blind documentation testing.
Knowledge Gaps
Knowledge Gap: Suppressing
ASPIRECOMPUTE002What I needed to know: How a C# Aspire user suppresses the
ASPIRECOMPUTE002diagnostic.
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
apivariable contextWhat I needed to know: Whether
apiin 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.
| const data = await aks.addPersistentVolume("data"); | ||
| await data.withCapacity("20Gi"); | ||
|
|
||
| await api.withKubernetesPersistentVolumeMount(data, "/data"); |
There was a problem hiding this comment.
api is not declared in this TypeScript example. Could we add the project before mounting the volume, matching the C# tab?
Documents changes from microsoft/aspire#19226
@mitchdennyTargeting
release/13.5— the latest release branch onmicrosoft/aspire.dev— becauserelease/13.6(from the source PR milestone13.6) does not exist there.Why
microsoft/aspire#19226 adds
AddPersistentVolumedirectly toAzureKubernetesEnvironmentResource, 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-specificAddPersistentVolume/addPersistentVolumecall (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.