# K3sBuilderExtensions Methods

- Package: [CommunityToolkit.Aspire.Hosting.K3s](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s.md)
- Type: [K3sBuilderExtensions](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3sbuilderextensions.md)
- Kind: `Methods`
- Members: `11`

Provides extension methods for adding k3s cluster resources to an `Hosting.IDistributedApplicationBuilder`.

<a id="addk3scluster"></a>
<a id="addk3scluster-idistributedapplicationbuilder-string-int-int"></a>

## AddK3sCluster(IDistributedApplicationBuilder, string, int?, int?)

- Name: `AddK3sCluster(IDistributedApplicationBuilder, string, int?, int?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<K3sClusterResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d479e13473b1d29d06b974f144a0049289a3cb5c/src/CommunityToolkit.Aspire.Hosting.K3s/K3sBuilderExtensions.cs#L67-L268)

Adds a k3s Kubernetes cluster to the distributed application.

```csharp
public static class K3sBuilderExtensions
{
    public static IResourceBuilder<K3sClusterResource> AddK3sCluster(
        this IDistributedApplicationBuilder builder,
        string name,
        int? apiServerPort = null,
        int? agentCount = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IDistributedApplicationBuilder`)
  The distributed application builder.
- `name` (`string`)
  The resource name. Also used as the DNS hostname by which containers in the DCP network reach the cluster's API server (e.g. `https://{name}:6443`).
- `apiServerPort` (`int?`) `optional`
  Host port to bind the Kubernetes API server (port 6443) to. When `null` (the default) a random available port is assigned.
- `agentCount` (`int?`) `optional`
  Number of k3s agent (worker) nodes to add. When `null` (the default) a single-node cluster is created -- the server node acts as both control-plane and worker. Equivalent to calling [K3sBuilderExtensions.WithAgentCount(IResourceBuilder<K3sClusterResource>, int)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3sbuilderextensions/methods.md#withagentcount-iresourcebuilder-k3sclusterresource-int) on the returned builder.

## Returns

`IResourceBuilder<K3sClusterResource>` -- A builder for the [K3sClusterResource](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3sclusterresource.md).

## Exceptions

- `ArgumentNullException` -- `builder` or `name` is `null`.

## Remarks

The cluster runs as a privileged container using the `rancher/k3s` image. No host-side `kubectl`, `helm`, or `k3s` binaries are required.

Three kubeconfig variants are written to `{AppHostDirectory}/.k3s/{name}/` when the cluster becomes ready:

- `local/kubeconfig.yaml` -- injected into host processes via `KUBECONFIG`.
- `container/kubeconfig.yaml` -- bind-mounted into containers via `KUBECONFIG`.

Call `WithReference(cluster)` on a dependent resource builder to inject these credentials automatically.

All other cluster options are available as fluent builder methods: [K3sBuilderExtensions.WithK3sVersion(IResourceBuilder<K3sClusterResource>, string)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3sbuilderextensions/methods.md#withk3sversion-iresourcebuilder-k3sclusterresource-string), [K3sBuilderExtensions.WithAgentCount(IResourceBuilder<K3sClusterResource>, int)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3sbuilderextensions/methods.md#withagentcount-iresourcebuilder-k3sclusterresource-int), [K3sBuilderExtensions.WithPodSubnet(IResourceBuilder<K3sClusterResource>, string)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3sbuilderextensions/methods.md#withpodsubnet-iresourcebuilder-k3sclusterresource-string), [K3sBuilderExtensions.WithServiceSubnet(IResourceBuilder<K3sClusterResource>, string)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3sbuilderextensions/methods.md#withservicesubnet-iresourcebuilder-k3sclusterresource-string), [K3sBuilderExtensions.WithDisabledComponent(IResourceBuilder<K3sClusterResource>, string)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3sbuilderextensions/methods.md#withdisabledcomponent-iresourcebuilder-k3sclusterresource-string), [K3sBuilderExtensions.WithExtraArg(IResourceBuilder<K3sClusterResource>, string)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3sbuilderextensions/methods.md#withextraarg-iresourcebuilder-k3sclusterresource-string), [K3sBuilderExtensions.WithDataVolume(IResourceBuilder<K3sClusterResource>, string?)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3sbuilderextensions/methods.md#withdatavolume-iresourcebuilder-k3sclusterresource-string), [K3sBuilderExtensions.WithHelmImage(IResourceBuilder<K3sClusterResource>, string?, string?, string?)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3sbuilderextensions/methods.md#withhelmimage-iresourcebuilder-k3sclusterresource-string-string-string), [K3sBuilderExtensions.WithKubectlImage(IResourceBuilder<K3sClusterResource>, string?, string?, string?)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3sbuilderextensions/methods.md#withkubectlimage-iresourcebuilder-k3sclusterresource-string-string-string), and [K3sBuilderExtensions.WithLifetime(IResourceBuilder<K3sClusterResource>, ContainerLifetime)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3sbuilderextensions/methods.md#withlifetime-iresourcebuilder-k3sclusterresource-containerlifetime).

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withagentcount"></a>
<a id="withagentcount-iresourcebuilder-k3sclusterresource-int"></a>

## WithAgentCount(IResourceBuilder<K3sClusterResource>, int)

- Name: `WithAgentCount(IResourceBuilder<K3sClusterResource>, int)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<K3sClusterResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d479e13473b1d29d06b974f144a0049289a3cb5c/src/CommunityToolkit.Aspire.Hosting.K3s/K3sBuilderExtensions.cs#L464-L475)

Sets the number of k3s agent (worker) nodes to add to the cluster.

```csharp
public static class K3sBuilderExtensions
{
    public static IResourceBuilder<K3sClusterResource> WithAgentCount(
        this IResourceBuilder<K3sClusterResource> builder,
        int count)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<K3sClusterResource>`)
  The k3s cluster resource builder.
- `count` (`int`)
  The number of agent nodes. Zero or greater. Defaults to `0` (single-node cluster -- the server node acts as both control-plane and worker).

## Returns

`IResourceBuilder<K3sClusterResource>` -- The same builder, for chaining.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.
- `ArgumentOutOfRangeException` -- `count` is negative.

## Remarks

Agent nodes connect to the server via DCP DNS ( `https://{name}:6443`) and use k3s's built-in retry loop, so no explicit `WaitFor` is needed. The cluster health check waits for `1 + count` nodes to reach `Ready` state before reporting healthy. Use [K3sBuilderExtensions.WithLifetime(IResourceBuilder<K3sClusterResource>, ContainerLifetime)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3sbuilderextensions/methods.md#withlifetime-iresourcebuilder-k3sclusterresource-containerlifetime) with `ContainerLifetime.Persistent` to keep agents alive across AppHost restarts and avoid node password hash mismatches.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withdatavolume"></a>
<a id="withdatavolume-iresourcebuilder-k3sclusterresource-string"></a>

## WithDataVolume(IResourceBuilder<K3sClusterResource>, string?)

- Name: `WithDataVolume(IResourceBuilder<K3sClusterResource>, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<K3sClusterResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d479e13473b1d29d06b974f144a0049289a3cb5c/src/CommunityToolkit.Aspire.Hosting.K3s/K3sBuilderExtensions.cs#L427-L438)

Mounts a named Docker volume at the k3s data directory so cluster state persists across AppHost restarts.

```csharp
public static class K3sBuilderExtensions
{
    public static IResourceBuilder<K3sClusterResource> WithDataVolume(
        this IResourceBuilder<K3sClusterResource> builder,
        string? name = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<K3sClusterResource>`)
  The k3s cluster resource builder.
- `name` (`string?`) `optional`
  Optional volume name. When `null` (the default) a name is generated from the application and resource names.

## Returns

`IResourceBuilder<K3sClusterResource>` -- The same builder, for chaining.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.

## Remarks

The volume covers `/var/lib/rancher/k3s`, which contains the SQLite database, TLS certificates, and kubeconfig. Without this volume the cluster starts fresh on every AppHost launch. Combine with `ContainerLifetime.Persistent` on the cluster resource and its dependent Helm releases to avoid re-installing charts on every start.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withdisabledcomponent"></a>
<a id="withdisabledcomponent-iresourcebuilder-k3sclusterresource-string"></a>

## WithDisabledComponent(IResourceBuilder<K3sClusterResource>, string)

- Name: `WithDisabledComponent(IResourceBuilder<K3sClusterResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<K3sClusterResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d479e13473b1d29d06b974f144a0049289a3cb5c/src/CommunityToolkit.Aspire.Hosting.K3s/K3sBuilderExtensions.cs#L373-L376)

Disables a built-in k3s component ( `--disable=<component>`).

```csharp
public static class K3sBuilderExtensions
{
    public static IResourceBuilder<K3sClusterResource> WithDisabledComponent(
        this IResourceBuilder<K3sClusterResource> builder,
        string component)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<K3sClusterResource>`)
  The k3s cluster resource builder.
- `component` (`string`)
  The component name to disable. Common values include `traefik`, `servicelb`, `metrics-server`, `coredns`, and `local-storage`. Call this method multiple times to disable more than one component.

## Returns

`IResourceBuilder<K3sClusterResource>` -- The same builder, for chaining.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.
- `ArgumentException` -- `component` is `null` or whitespace.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withextraarg"></a>
<a id="withextraarg-iresourcebuilder-k3sclusterresource-string"></a>

## WithExtraArg(IResourceBuilder<K3sClusterResource>, string)

- Name: `WithExtraArg(IResourceBuilder<K3sClusterResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<K3sClusterResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d479e13473b1d29d06b974f144a0049289a3cb5c/src/CommunityToolkit.Aspire.Hosting.K3s/K3sBuilderExtensions.cs#L399-L402)

Appends a raw argument to the `k3s server` command line.

```csharp
public static class K3sBuilderExtensions
{
    public static IResourceBuilder<K3sClusterResource> WithExtraArg(
        this IResourceBuilder<K3sClusterResource> builder,
        string arg)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<K3sClusterResource>`)
  The k3s cluster resource builder.
- `arg` (`string`)
  The raw argument to append, e.g. `--write-kubeconfig-mode=644`. Call this method multiple times to append additional arguments.

## Returns

`IResourceBuilder<K3sClusterResource>` -- The same builder, for chaining.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.
- `ArgumentException` -- `arg` is `null` or whitespace.

## Remarks

Use [K3sBuilderExtensions.WithDisabledComponent(IResourceBuilder<K3sClusterResource>, string)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3sbuilderextensions/methods.md#withdisabledcomponent-iresourcebuilder-k3sclusterresource-string) or the dedicated CIDR methods when possible. This method is intended for flags that have no dedicated helper.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withhelmimage"></a>
<a id="withhelmimage-iresourcebuilder-k3sclusterresource-string-string-string"></a>

## WithHelmImage(IResourceBuilder<K3sClusterResource>, string?, string?, string?)

- Name: `WithHelmImage(IResourceBuilder<K3sClusterResource>, string?, string?, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<K3sClusterResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d479e13473b1d29d06b974f144a0049289a3cb5c/src/CommunityToolkit.Aspire.Hosting.K3s/K3sBuilderExtensions.cs#L495-L498)

Overrides the container image used to run `helm upgrade --install` for all [HelmReleaseResource](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/helmreleaseresource.md) children of this cluster.

```csharp
public static class K3sBuilderExtensions
{
    public static IResourceBuilder<K3sClusterResource> WithHelmImage(
        this IResourceBuilder<K3sClusterResource> builder,
        string? tag = null,
        string? image = null,
        string? registry = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<K3sClusterResource>`)
  The k3s cluster resource builder.
- `tag` (`string?`) `optional`
  Image tag, e.g. `3.18.0`. `null` keeps the current value.
- `image` (`string?`) `optional`
  Image name, e.g. `alpine/helm`. `null` keeps the current value.
- `registry` (`string?`) `optional`
  Registry, e.g. `docker.io`. `null` keeps the current value.

## Returns

`IResourceBuilder<K3sClusterResource>` -- The same builder, for chaining.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withk3sversion"></a>
<a id="withk3sversion-iresourcebuilder-k3sclusterresource-string"></a>

## WithK3sVersion(IResourceBuilder<K3sClusterResource>, string)

- Name: `WithK3sVersion(IResourceBuilder<K3sClusterResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<K3sClusterResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d479e13473b1d29d06b974f144a0049289a3cb5c/src/CommunityToolkit.Aspire.Hosting.K3s/K3sBuilderExtensions.cs#L292-L315)

Sets the k3s image version used by the cluster server and all its agent nodes.

```csharp
public static class K3sBuilderExtensions
{
    public static IResourceBuilder<K3sClusterResource> WithK3sVersion(
        this IResourceBuilder<K3sClusterResource> builder,
        string tag)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<K3sClusterResource>`)
  The k3s cluster resource builder.
- `tag` (`string`)
  The k3s container image tag, e.g. `v1.32.3-k3s1`. Must follow the `v{major}.{minor}.{patch}-k3s{n}` format.

## Returns

`IResourceBuilder<K3sClusterResource>` -- The same builder, for chaining.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.
- `ArgumentException` -- `tag` is `null` or whitespace.

## Remarks

All agent nodes are immediately synced to the same tag to prevent version skew beyond the Kubernetes-supported ±1 minor version limit. The image tag is part of the DCP container identity, so synchronisation must happen at configuration time.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withkubectlimage"></a>
<a id="withkubectlimage-iresourcebuilder-k3sclusterresource-string-string-string"></a>

## WithKubectlImage(IResourceBuilder<K3sClusterResource>, string?, string?, string?)

- Name: `WithKubectlImage(IResourceBuilder<K3sClusterResource>, string?, string?, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<K3sClusterResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d479e13473b1d29d06b974f144a0049289a3cb5c/src/CommunityToolkit.Aspire.Hosting.K3s/K3sBuilderExtensions.cs#L518-L521)

Overrides the container image used to run `kubectl apply` for all [K8sManifestResource](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k8smanifestresource.md) children of this cluster.

```csharp
public static class K3sBuilderExtensions
{
    public static IResourceBuilder<K3sClusterResource> WithKubectlImage(
        this IResourceBuilder<K3sClusterResource> builder,
        string? tag = null,
        string? image = null,
        string? registry = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<K3sClusterResource>`)
  The k3s cluster resource builder.
- `tag` (`string?`) `optional`
  Image tag, e.g. `1.37.0`. `null` keeps the current value.
- `image` (`string?`) `optional`
  Image name, e.g. `alpine/kubectl`. `null` keeps the current value.
- `registry` (`string?`) `optional`
  Registry, e.g. `docker.io`. `null` keeps the current value.

## Returns

`IResourceBuilder<K3sClusterResource>` -- The same builder, for chaining.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withlifetime"></a>
<a id="withlifetime-iresourcebuilder-k3sclusterresource-containerlifetime"></a>

## WithLifetime(IResourceBuilder<K3sClusterResource>, ContainerLifetime)

- Name: `WithLifetime(IResourceBuilder<K3sClusterResource>, ContainerLifetime)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<K3sClusterResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d479e13473b1d29d06b974f144a0049289a3cb5c/src/CommunityToolkit.Aspire.Hosting.K3s/K3sBuilderExtensions.cs#L543-L556)

Sets the container lifetime for the k3s cluster and all its agent nodes.

```csharp
public static class K3sBuilderExtensions
{
    public static IResourceBuilder<K3sClusterResource> WithLifetime(
        this IResourceBuilder<K3sClusterResource> builder,
        ContainerLifetime lifetime)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<K3sClusterResource>`)
  The k3s cluster resource builder.
- `lifetime` (`ContainerLifetime`)
  The container lifetime to apply.

## Returns

`IResourceBuilder<K3sClusterResource>` -- The same builder, for chaining.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.

## Remarks

Agent nodes are propagated immediately because DCP uses `ApplicationModel.ContainerLifetimeAnnotation` to compute container identity. Deferring propagation to `BeforeStartEvent` would be too late -- DCP determines whether to reuse or recreate a persistent container before that event fires, so agents would lose their persistent identity and be recreated as new containers each run.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withpodsubnet"></a>
<a id="withpodsubnet-iresourcebuilder-k3sclusterresource-string"></a>

## WithPodSubnet(IResourceBuilder<K3sClusterResource>, string)

- Name: `WithPodSubnet(IResourceBuilder<K3sClusterResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<K3sClusterResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d479e13473b1d29d06b974f144a0049289a3cb5c/src/CommunityToolkit.Aspire.Hosting.K3s/K3sBuilderExtensions.cs#L331-L334)

Sets the CIDR range for pod IP addresses ( `--cluster-cidr`).

```csharp
public static class K3sBuilderExtensions
{
    public static IResourceBuilder<K3sClusterResource> WithPodSubnet(
        this IResourceBuilder<K3sClusterResource> builder,
        string cidr)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<K3sClusterResource>`)
  The k3s cluster resource builder.
- `cidr` (`string`)
  The pod subnet in CIDR notation, e.g. `10.42.0.0/16`.

## Returns

`IResourceBuilder<K3sClusterResource>` -- The same builder, for chaining.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.
- `ArgumentException` -- `cidr` is `null` or whitespace.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withservicesubnet"></a>
<a id="withservicesubnet-iresourcebuilder-k3sclusterresource-string"></a>

## WithServiceSubnet(IResourceBuilder<K3sClusterResource>, string)

- Name: `WithServiceSubnet(IResourceBuilder<K3sClusterResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<K3sClusterResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d479e13473b1d29d06b974f144a0049289a3cb5c/src/CommunityToolkit.Aspire.Hosting.K3s/K3sBuilderExtensions.cs#L350-L353)

Sets the CIDR range for Service cluster IPs ( `--service-cidr`).

```csharp
public static class K3sBuilderExtensions
{
    public static IResourceBuilder<K3sClusterResource> WithServiceSubnet(
        this IResourceBuilder<K3sClusterResource> builder,
        string cidr)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<K3sClusterResource>`)
  The k3s cluster resource builder.
- `cidr` (`string`)
  The service subnet in CIDR notation, e.g. `10.43.0.0/16`.

## Returns

`IResourceBuilder<K3sClusterResource>` -- The same builder, for chaining.

## Exceptions

- `ArgumentNullException` -- `builder` is `null`.
- `ArgumentException` -- `cidr` is `null` or whitespace.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.