Skip to content

[docs] Document AddPersistentVolume on AKS environments #1474

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aspire-repo-bot wants to merge 1 commit into
base: release/13.5
Choose a base branch
from
+48 −0
Open

[docs] Document AddPersistentVolume on AKS environments #1474

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions src/frontend/src/content/docs/deployment/kubernetes/persistent-volumes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -234,10 +234,15 @@ spec:
To generate and inspect the Helm chart for yourself, see [Deploy to Kubernetes clusters](/deployment/kubernetes/clusters/).
</LearnMore>

## Persistent volumes on AKS

`AddPersistentVolume` is also available directly on an [Azure Kubernetes Service (AKS) environment](/integrations/cloud/azure/aks/#add-a-persistent-volume), so you don't need to reach through to the underlying Kubernetes environment when targeting AKS. The AKS overload forwards to the same publisher described on this page, and uses the same configuration and binding APIs.

## See also

- [Kubernetes integration](/integrations/compute/kubernetes/)
- [Deploy to Kubernetes clusters](/deployment/kubernetes/clusters/)
- [Deploy to AKS](/deployment/kubernetes/aks/)
- [Azure Kubernetes Service (AKS) integration](/integrations/cloud/azure/aks/)
- [Persist data with volumes](/fundamentals/persist-data-volumes/)
- [Kubernetes persistent volumes documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)
43 changes: 43 additions & 0 deletions src/frontend/src/content/docs/integrations/cloud/azure/aks/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,48 @@ await worker.withNodePool(gpuPool);
</TabItem>
</Tabs>

## Add a persistent volume

<Aside type="note">
Persistent volume APIs are experimental. In C#, suppress the `ASPIRECOMPUTE002` diagnostic to use them.
</Aside>

Call `AddPersistentVolume` directly on the AKS environment to model durable storage without reaching through to the underlying Kubernetes integration. The call forwards to the AKS environment's Kubernetes publisher, so the same configuration methods and workload-binding APIs described in [Persistent volumes on Kubernetes](/deployment/kubernetes/persistent-volumes/) apply:

<Tabs syncKey='aspire-lang'>
<TabItem id='csharp' label='C#'>
```csharp title="AppHost.cs"
var aks = builder.AddAzureKubernetesEnvironment("aks");

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

builder.AddProject<Projects.Api>("api")
.WithPersistentVolume(data, "/data");
```
</TabItem>
<TabItem id='typescript' label='TypeScript'>
```typescript title="apphost.mts"
const aks = await builder.addAzureKubernetesEnvironment("aks");

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

await api.withKubernetesPersistentVolumeMount(data, "/data");
Comment on lines +133 to +138
```
</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.

@alistairmatthews Alistair Matthews (alistairmatthews) Aug 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


<Aside type="note">
Azure Files-specific APIs are intentionally deferred until managed-identity mounting can be modeled securely.

@alistairmatthews Alistair Matthews (alistairmatthews) Aug 12, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

</Aside>

<LearnMore>
For the full set of configuration methods (storage class, capacity, access modes, annotations) and how to bind volumes to workloads, see [Persistent volumes on Kubernetes](/deployment/kubernetes/persistent-volumes/).
</LearnMore>

## Publishing and deployment

The AKS integration supports both [`aspire publish`](/reference/cli/commands/aspire-publish/) (generate Helm chart and Bicep artifacts) and [`aspire deploy`](/reference/cli/commands/aspire-deploy/) (provision Azure infrastructure and deploy in a single command).
Expand All @@ -119,6 +161,7 @@ For a complete end-to-end walkthrough, see [Deploy to AKS](/deployment/kubernete
- [Deploy to AKS](/deployment/kubernetes/aks/)
- [Deploy to Kubernetes](/deployment/kubernetes/)
- [Kubernetes integration](/integrations/compute/kubernetes/)
- [Persistent volumes on Kubernetes](/deployment/kubernetes/persistent-volumes/)
- [Azure Container Apps integration](/integrations/cloud/azure/configure-container-apps/)
- [Deploy to Azure](/deployment/azure/)
- [Azure compute integrations overview](/integrations/cloud/azure/overview/)
Expand Down
Loading