KubernetesPersistentVolumeExtensions Methods

AddPersistentVolume(IResourceBuilder<KubernetesEnvironmentResource>, string)extensionIResourceBuilder<KubernetesPersistentVolumeResource>

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.

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

KubernetesPersistentVolumeExtensions.cs#L50-L63

Parameters

builderIResourceBuilder<KubernetesEnvironmentResource>The Kubernetes environment resource builder.

namestringThe 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, add a WithVolume("name", "/path") on the workload using the same name.

Returns

IResourceBuilder<KubernetesPersistentVolumeResource>A builder for the new KubernetesPersistentVolumeResource.

Examples

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

WithAccessMode(IResourceBuilder<KubernetesPersistentVolumeResource>, PersistentVolumeAccessMode)extensionIResourceBuilder<KubernetesPersistentVolumeResource>

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 is used.

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

KubernetesPersistentVolumeExtensions.cs#L165-L172

Parameters

builderIResourceBuilder<KubernetesPersistentVolumeResource>The persistent volume resource builder.

accessModePersistentVolumeAccessModeThe access mode to add.

Returns

IResourceBuilder<KubernetesPersistentVolumeResource>The same builder for chaining.

WithCapacity(IResourceBuilder<KubernetesPersistentVolumeResource>, string)extensionIResourceBuilder<KubernetesPersistentVolumeResource>

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

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

KubernetesPersistentVolumeExtensions.cs

Parameters

builderIResourceBuilder<KubernetesPersistentVolumeResource>The persistent volume resource builder.

capacitystringA Kubernetes quantity string (e.g. "10Gi", "500Mi").

Returns

IResourceBuilder<KubernetesPersistentVolumeResource>The same builder for chaining.

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

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

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

KubernetesPersistentVolumeExtensions.cs

Parameters

builderIResourceBuilder<KubernetesPersistentVolumeResource>The persistent volume resource builder.

capacityIResourceBuilder<ParameterResource>A parameter resource builder for the capacity quantity string.

Returns

IResourceBuilder<KubernetesPersistentVolumeResource>The same builder for chaining.

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

Binds a workload to a Kubernetes KubernetesPersistentVolumeResource using name matching. The workload must 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.

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

KubernetesPersistentVolumeExtensions.cs#L266-L287

Parameters

builderIResourceBuilder<T>The workload resource builder.

volumeIResourceBuilder<KubernetesPersistentVolumeResource>The persistent volume resource to bind to.

Returns

IResourceBuilder<T>The same builder for chaining.

Remarks

To bind a workload that does not 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 to customize the pod security context when a different group or policy is required.

Examples

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"

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

Binds a workload to a Kubernetes KubernetesPersistentVolumeResource 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.

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

KubernetesPersistentVolumeExtensions.cs#L333

Parameters

builderIResourceBuilder<T>The workload resource builder.

volumeIResourceBuilder<KubernetesPersistentVolumeResource>The persistent volume resource to bind to.

mountPathstringThe path inside the container where the volume will be mounted (e.g. "/var/lib/postgresql/data").

isReadOnlybooloptionalWhen 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 to customize the pod security context when a different group or policy is required.

Examples

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

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

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

Binds a workload to a Kubernetes KubernetesPersistentVolumeResource, mounts it at the specified path when deployed, and exposes the effective storage path through an environment variable.

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

KubernetesPersistentVolumeExtensions.cs#L372-L374

Parameters

builderIResourceBuilder<T>The workload resource builder.

volumeIResourceBuilder<KubernetesPersistentVolumeResource>The persistent volume resource to bind to.

mountPathstringThe path inside the deployed container where the volume is mounted.

envstringThe environment variable that receives the effective storage path.

isReadOnlybooloptionalWhen true, mounts the deployed volume read-only.

Returns

IResourceBuilder<T>The same builder for chaining.

Remarks

In run mode, projects and executables receive a deterministic host directory under the AppHost's ApplicationModel.IAspireStore. Containers receive the in-container mountPath. In publish and deploy modes, every workload receives mountPath.

Examples

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

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

WithStorageClass(IResourceBuilder<KubernetesPersistentVolumeResource>, string)extensionIResourceBuilder<KubernetesPersistentVolumeResource>

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

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

KubernetesPersistentVolumeExtensions.cs

Parameters

builderIResourceBuilder<KubernetesPersistentVolumeResource>The persistent volume resource builder.

storageClassNamestringThe storage class name (e.g. "managed-csi", "gp3").

Returns

IResourceBuilder<KubernetesPersistentVolumeResource>The same builder for chaining.

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

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

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

KubernetesPersistentVolumeExtensions.cs

Parameters

builderIResourceBuilder<KubernetesPersistentVolumeResource>The persistent volume resource builder.

storageClassNameIResourceBuilder<ParameterResource>A parameter resource builder for the storage class name.

Returns

IResourceBuilder<KubernetesPersistentVolumeResource>The same builder for chaining.

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

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.

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

KubernetesPersistentVolumeExtensions.cs

Parameters

builderIResourceBuilder<KubernetesPersistentVolumeResource>The persistent volume resource builder.

keystringThe annotation key (e.g. "volume.beta.kubernetes.io/storage-provisioner").

valuestringThe annotation value.

Returns

IResourceBuilder<KubernetesPersistentVolumeResource>The same builder for chaining.

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

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

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

KubernetesPersistentVolumeExtensions.cs

Parameters

builderIResourceBuilder<KubernetesPersistentVolumeResource>The persistent volume resource builder.

keystringThe annotation key.

valueIResourceBuilder<ParameterResource>A parameter resource builder for the annotation value.

Returns

IResourceBuilder<KubernetesPersistentVolumeResource>The same builder for chaining.