# KubernetesPersistentVolumeExtensions Methods

- Package: [Aspire.Hosting.Kubernetes](/reference/api/csharp/aspire.hosting.kubernetes.md)
- Type: [KubernetesPersistentVolumeExtensions](/reference/api/csharp/aspire.hosting.kubernetes/kubernetespersistentvolumeextensions.md)
- Kind: `Methods`
- Members: `10`

Provides extension methods for configuring Kubernetes [KubernetesPersistentVolumeResource](/reference/api/csharp/aspire.hosting.kubernetes/kubernetespersistentvolumeresource.md) resources and binding workloads to them.

<a id="addpersistentvolume"></a>
<a id="addpersistentvolume-iresourcebuilder-kubernetesenvironmentresource-string"></a>

## AddPersistentVolume(IResourceBuilder<KubernetesEnvironmentResource>, string)

- Name: `AddPersistentVolume(IResourceBuilder<KubernetesEnvironmentResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesPersistentVolumeResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/69db530a4816698cf1d5fa4557933e0ac4f127c6/src/Aspire.Hosting.Kubernetes/KubernetesPersistentVolumeExtensions.cs#L47-L60)

Adds a Kubernetes PersistentVolumeClaim resource to the application model as a child of the specified Kubernetes environment. The resource generates a `v1.PersistentVolumeClaim` manifest in the Helm chart output at publish time.

```csharp
public static class KubernetesPersistentVolumeExtensions
{
    public static IResourceBuilder<KubernetesPersistentVolumeResource> AddPersistentVolume(
        this IResourceBuilder<KubernetesEnvironmentResource> builder,
        string name)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesEnvironmentResource>`)
  The Kubernetes environment resource builder.
- `name` (`string`)
  The name of the persistent volume resource. Used as the generated PVC's `metadata.name` after lower-casing. To bind a workload using the name-match overload of [KubernetesPersistentVolumeExtensions.WithPersistentVolume(IResourceBuilder<T>, IResourceBuilder<KubernetesPersistentVolumeResource>)](/reference/api/csharp/aspire.hosting.kubernetes/kubernetespersistentvolumeextensions/methods.md#withpersistentvolume-iresourcebuilder-t-iresourcebuilder-kubernetespersistentvolumeresource), add a `WithVolume("name", "/path")` on the workload using the same `name`.

## Returns

`IResourceBuilder<KubernetesPersistentVolumeResource>` -- A builder for the new [KubernetesPersistentVolumeResource](/reference/api/csharp/aspire.hosting.kubernetes/kubernetespersistentvolumeresource.md).

## Examples

```csharp
var k8s = builder.AddKubernetesEnvironment("k8s");
var data = k8s.AddPersistentVolume("data")
    .WithStorageClass("managed-csi")
    .WithCapacity("20Gi");
```

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withaccessmode"></a>
<a id="withaccessmode-iresourcebuilder-kubernetespersistentvolumeresource-persistentvolumeaccessmode"></a>

## WithAccessMode(IResourceBuilder<KubernetesPersistentVolumeResource>, PersistentVolumeAccessMode)

- Name: `WithAccessMode(IResourceBuilder<KubernetesPersistentVolumeResource>, PersistentVolumeAccessMode)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesPersistentVolumeResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/69db530a4816698cf1d5fa4557933e0ac4f127c6/src/Aspire.Hosting.Kubernetes/KubernetesPersistentVolumeExtensions.cs#L162-L169)

Adds an access mode to the PVC's `spec.accessModes`. Call multiple times to declare more than one mode. When unset, the environment's [KubernetesEnvironmentResource.DefaultStorageReadWritePolicy](/reference/api/csharp/aspire.hosting.kubernetes/kubernetesenvironmentresource/properties.md#defaultstoragereadwritepolicy) is used.

```csharp
public static class KubernetesPersistentVolumeExtensions
{
    public static IResourceBuilder<KubernetesPersistentVolumeResource> WithAccessMode(
        this IResourceBuilder<KubernetesPersistentVolumeResource> builder,
        PersistentVolumeAccessMode accessMode)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesPersistentVolumeResource>`)
  The persistent volume resource builder.
- `accessMode` ([PersistentVolumeAccessMode](/reference/api/csharp/aspire.hosting.kubernetes/persistentvolumeaccessmode.md))
  The access mode to add.

## Returns

`IResourceBuilder<KubernetesPersistentVolumeResource>` -- The same builder for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withcapacity"></a>
<a id="withcapacity-iresourcebuilder-kubernetespersistentvolumeresource-string"></a>

## WithCapacity(IResourceBuilder<KubernetesPersistentVolumeResource>, string)

- Name: `WithCapacity(IResourceBuilder<KubernetesPersistentVolumeResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesPersistentVolumeResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/69db530a4816698cf1d5fa4557933e0ac4f127c6/src/Aspire.Hosting.Kubernetes/KubernetesPersistentVolumeExtensions.cs)

Sets the requested storage capacity on the PVC's `spec.resources.requests.storage` field.

```csharp
public static class KubernetesPersistentVolumeExtensions
{
    public static IResourceBuilder<KubernetesPersistentVolumeResource> WithCapacity(
        this IResourceBuilder<KubernetesPersistentVolumeResource> builder,
        string capacity)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesPersistentVolumeResource>`)
  The persistent volume resource builder.
- `capacity` (`string`)
  A Kubernetes quantity string (e.g. `"10Gi"`, `"500Mi"`).

## Returns

`IResourceBuilder<KubernetesPersistentVolumeResource>` -- The same builder for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withcapacity-iresourcebuilder-kubernetespersistentvolumeresource-iresourcebuilder-parameterresource"></a>

## WithCapacity(IResourceBuilder<KubernetesPersistentVolumeResource>, IResourceBuilder<ParameterResource>)

- Name: `WithCapacity(IResourceBuilder<KubernetesPersistentVolumeResource>, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesPersistentVolumeResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/69db530a4816698cf1d5fa4557933e0ac4f127c6/src/Aspire.Hosting.Kubernetes/KubernetesPersistentVolumeExtensions.cs)

Sets the requested storage capacity using a parameter resolved at deploy time.

```csharp
public static class KubernetesPersistentVolumeExtensions
{
    public static IResourceBuilder<KubernetesPersistentVolumeResource> WithCapacity(
        this IResourceBuilder<KubernetesPersistentVolumeResource> builder,
        IResourceBuilder<ParameterResource> capacity)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesPersistentVolumeResource>`)
  The persistent volume resource builder.
- `capacity` (`IResourceBuilder<ParameterResource>`)
  A parameter resource builder for the capacity quantity string.

## Returns

`IResourceBuilder<KubernetesPersistentVolumeResource>` -- The same builder for chaining.

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting.Kubernetes/withCapacityParam`

<a id="withpersistentvolume"></a>
<a id="withpersistentvolume-iresourcebuilder-t-iresourcebuilder-kubernetespersistentvolumeresource"></a>

## WithPersistentVolume(IResourceBuilder<T>, IResourceBuilder<KubernetesPersistentVolumeResource>)

- Name: `WithPersistentVolume(IResourceBuilder<T>, IResourceBuilder<KubernetesPersistentVolumeResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/69db530a4816698cf1d5fa4557933e0ac4f127c6/src/Aspire.Hosting.Kubernetes/KubernetesPersistentVolumeExtensions.cs#L263-L267)

Binds a workload to a Kubernetes [KubernetesPersistentVolumeResource](/reference/api/csharp/aspire.hosting.kubernetes/kubernetespersistentvolumeresource.md) using name matching. The workload must already declare a volume with a matching `source` name (typically via `WithVolume("name", "/path")` or an integration helper such as Postgres' `WithDataVolume()`). The publisher rewrites that volume's pod-spec entry to reference the generated PVC and promotes the workload to a `StatefulSet`.

```csharp
public static class KubernetesPersistentVolumeExtensions
{
    public static IResourceBuilder<T> WithPersistentVolume<T>(
        this IResourceBuilder<T> builder,
        IResourceBuilder<KubernetesPersistentVolumeResource> volume)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The workload resource builder.
- `volume` (`IResourceBuilder<KubernetesPersistentVolumeResource>`)
  The persistent volume resource to bind to.

## Returns

`IResourceBuilder<T>` -- The same builder for chaining.

## Remarks

To bind a workload that does not already have a matching named mount (for example a `ProjectResource`), use the overload that accepts a `mountPath` instead. The generated pod uses an Aspire-managed `fsGroup` of `2000` with an `OnRootMismatch` change policy so non-root containers can access supported volumes without matching the image's primary group. Use [KubernetesServiceExtensions.PublishAsKubernetesService(IResourceBuilder<T>, Action<KubernetesResource>)](/reference/api/csharp/aspire.hosting.kubernetes/kubernetesserviceextensions/methods.md#publishaskubernetesservice-iresourcebuilder-t-action-kubernetesresource) to customize the pod security context when a different group or policy is required.

## Examples

```csharp
var pgData = k8s.AddPersistentVolume("pg-data")
    .WithStorageClass("managed-csi")
    .WithCapacity("20Gi");

var pg = builder.AddPostgres("pg")
    .WithDataVolume("pg-data")     // ContainerMountAnnotation source = "pg-data"
    .WithPersistentVolume(pgData); // matches by name "pg-data"
```

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting.Kubernetes/withKubernetesPersistentVolume`

<a id="withpersistentvolume-iresourcebuilder-t-iresourcebuilder-kubernetespersistentvolumeresource-string-bool"></a>

## WithPersistentVolume(IResourceBuilder<T>, IResourceBuilder<KubernetesPersistentVolumeResource>, string, bool)

- Name: `WithPersistentVolume(IResourceBuilder<T>, IResourceBuilder<KubernetesPersistentVolumeResource>, string, bool)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<T>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/69db530a4816698cf1d5fa4557933e0ac4f127c6/src/Aspire.Hosting.Kubernetes/KubernetesPersistentVolumeExtensions.cs#L312-L318)

Binds a workload to a Kubernetes [KubernetesPersistentVolumeResource](/reference/api/csharp/aspire.hosting.kubernetes/kubernetespersistentvolumeresource.md) and mounts it at the specified path inside the workload's container. Unlike the name-match overload this one creates the underlying mount itself, so it works for workloads that don't already declare a named volume -- including `ApplicationModel.ProjectResource`.

```csharp
public static class KubernetesPersistentVolumeExtensions
{
    public static IResourceBuilder<T> WithPersistentVolume<T>(
        this IResourceBuilder<T> builder,
        IResourceBuilder<KubernetesPersistentVolumeResource> volume,
        string mountPath,
        bool isReadOnly = false)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<T>`)
  The workload resource builder.
- `volume` (`IResourceBuilder<KubernetesPersistentVolumeResource>`)
  The persistent volume resource to bind to.
- `mountPath` (`string`)
  The path inside the container where the volume will be mounted (e.g. `"/var/lib/postgresql/data"`).
- `isReadOnly` (`bool`) `optional`
  When `true`, mounts the volume read-only.

## Returns

`IResourceBuilder<T>` -- The same builder for chaining.

## Remarks

The generated pod uses an Aspire-managed `fsGroup` of `2000` with an `OnRootMismatch` change policy so non-root containers can access supported volumes without matching the image's primary group. Use [KubernetesServiceExtensions.PublishAsKubernetesService(IResourceBuilder<T>, Action<KubernetesResource>)](/reference/api/csharp/aspire.hosting.kubernetes/kubernetesserviceextensions/methods.md#publishaskubernetesservice-iresourcebuilder-t-action-kubernetesresource) to customize the pod security context when a different group or policy is required.

## Examples

```csharp
var media = k8s.AddPersistentVolume("media")
    .WithStorageClass("azurefile-csi")
    .WithCapacity("100Gi")
    .WithAccessMode(PersistentVolumeAccessMode.ReadWriteMany);

builder.AddProject<MyApi>("api")
       .WithPersistentVolume(media, "/srv/media");
```

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting.Kubernetes/withKubernetesPersistentVolumeMount`

<a id="withstorageclass"></a>
<a id="withstorageclass-iresourcebuilder-kubernetespersistentvolumeresource-string"></a>

## WithStorageClass(IResourceBuilder<KubernetesPersistentVolumeResource>, string)

- Name: `WithStorageClass(IResourceBuilder<KubernetesPersistentVolumeResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesPersistentVolumeResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/69db530a4816698cf1d5fa4557933e0ac4f127c6/src/Aspire.Hosting.Kubernetes/KubernetesPersistentVolumeExtensions.cs)

Sets the Kubernetes storage class name on the PVC's `spec.storageClassName`. When unset, the cluster's default storage class is used.

```csharp
public static class KubernetesPersistentVolumeExtensions
{
    public static IResourceBuilder<KubernetesPersistentVolumeResource> WithStorageClass(
        this IResourceBuilder<KubernetesPersistentVolumeResource> builder,
        string storageClassName)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesPersistentVolumeResource>`)
  The persistent volume resource builder.
- `storageClassName` (`string`)
  The storage class name (e.g. `"managed-csi"`, `"gp3"`).

## Returns

`IResourceBuilder<KubernetesPersistentVolumeResource>` -- The same builder for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withstorageclass-iresourcebuilder-kubernetespersistentvolumeresource-iresourcebuilder-parameterresource"></a>

## WithStorageClass(IResourceBuilder<KubernetesPersistentVolumeResource>, IResourceBuilder<ParameterResource>)

- Name: `WithStorageClass(IResourceBuilder<KubernetesPersistentVolumeResource>, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesPersistentVolumeResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/69db530a4816698cf1d5fa4557933e0ac4f127c6/src/Aspire.Hosting.Kubernetes/KubernetesPersistentVolumeExtensions.cs)

Sets the Kubernetes storage class name using a parameter resolved at deploy time.

```csharp
public static class KubernetesPersistentVolumeExtensions
{
    public static IResourceBuilder<KubernetesPersistentVolumeResource> WithStorageClass(
        this IResourceBuilder<KubernetesPersistentVolumeResource> builder,
        IResourceBuilder<ParameterResource> storageClassName)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesPersistentVolumeResource>`)
  The persistent volume resource builder.
- `storageClassName` (`IResourceBuilder<ParameterResource>`)
  A parameter resource builder for the storage class name.

## Returns

`IResourceBuilder<KubernetesPersistentVolumeResource>` -- The same builder for chaining.

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting.Kubernetes/withStorageClassParam`

<a id="withvolumeannotation"></a>
<a id="withvolumeannotation-iresourcebuilder-kubernetespersistentvolumeresource-string-string"></a>

## WithVolumeAnnotation(IResourceBuilder<KubernetesPersistentVolumeResource>, string, string)

- Name: `WithVolumeAnnotation(IResourceBuilder<KubernetesPersistentVolumeResource>, string, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesPersistentVolumeResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/69db530a4816698cf1d5fa4557933e0ac4f127c6/src/Aspire.Hosting.Kubernetes/KubernetesPersistentVolumeExtensions.cs)

Adds a Kubernetes metadata annotation to the generated PVC. These flush to `metadata.annotations` on the rendered Kubernetes resource -- not Aspire `ApplicationModel.IResourceAnnotation` instances. Common uses: CSI driver hints, dynamic provisioner parameters, external-secrets selectors, or backup tooling tags.

```csharp
public static class KubernetesPersistentVolumeExtensions
{
    public static IResourceBuilder<KubernetesPersistentVolumeResource> WithVolumeAnnotation(
        this IResourceBuilder<KubernetesPersistentVolumeResource> builder,
        string key,
        string value)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesPersistentVolumeResource>`)
  The persistent volume resource builder.
- `key` (`string`)
  The annotation key (e.g. `"volume.beta.kubernetes.io/storage-provisioner"`).
- `value` (`string`)
  The annotation value.

## Returns

`IResourceBuilder<KubernetesPersistentVolumeResource>` -- The same builder for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withvolumeannotation-iresourcebuilder-kubernetespersistentvolumeresource-string-iresourcebuilder-parameterresource"></a>

## WithVolumeAnnotation(IResourceBuilder<KubernetesPersistentVolumeResource>, string, IResourceBuilder<ParameterResource>)

- Name: `WithVolumeAnnotation(IResourceBuilder<KubernetesPersistentVolumeResource>, string, IResourceBuilder<ParameterResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<KubernetesPersistentVolumeResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/69db530a4816698cf1d5fa4557933e0ac4f127c6/src/Aspire.Hosting.Kubernetes/KubernetesPersistentVolumeExtensions.cs)

Adds a Kubernetes metadata annotation with a parameter value resolved at deploy time.

```csharp
public static class KubernetesPersistentVolumeExtensions
{
    public static IResourceBuilder<KubernetesPersistentVolumeResource> WithVolumeAnnotation(
        this IResourceBuilder<KubernetesPersistentVolumeResource> builder,
        string key,
        IResourceBuilder<ParameterResource> value)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<KubernetesPersistentVolumeResource>`)
  The persistent volume resource builder.
- `key` (`string`)
  The annotation key.
- `value` (`IResourceBuilder<ParameterResource>`)
  A parameter resource builder for the annotation value.

## Returns

`IResourceBuilder<KubernetesPersistentVolumeResource>` -- The same builder for chaining.

## ATS metadata

### ATS export

- Capability ID: `Aspire.Hosting.Kubernetes/withVolumeAnnotationParam`