# K3sHelmBuilderExtensions Methods

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

Extension methods for adding Helm release resources to a k3s cluster.

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

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

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

Installs a Helm chart into the k3s cluster.

```csharp
public static class K3sHelmBuilderExtensions
{
    public static IResourceBuilder<HelmReleaseResource> AddHelmRelease(
        this IResourceBuilder<K3sClusterResource> builder,
        string name,
        string chart,
        string? repo = null,
        string? version = null,
        string @namespace = "default")
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<K3sClusterResource>`)
  The k3s cluster resource builder.
- `name` (`string`)
  The Aspire resource name; also used as the Helm release name passed to `helm upgrade --install`.
- `chart` (`string`)
  The chart name, e.g. `argo-cd` for a repo chart or `oci://registry/chart` for an OCI reference. Provide `repo` when using a named repo chart.
- `repo` (`string?`) `optional`
  Optional Helm repository URL, e.g. `https://argoproj.github.io/argo-helm`. When provided, the repo is added and updated before installation.
- `version` (`string?`) `optional`
  Optional chart version to pin, e.g. `7.8.0`. When `null` the latest version available in the repository is installed.
- `namespace` (`string`) `optional`
  The Kubernetes namespace to install the release into. The namespace is created automatically if it does not exist. Defaults to `default`.

## Returns

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

## Exceptions

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

## Remarks

The release runs as an `alpine/helm` container on the DCP network. No host-side `helm` binary is required. The container exits with code 0 when the release is fully installed and all workloads are ready. Use `WaitForCompletion(helmRelease)` on resources that must start only after the chart is ready.

Customize the release with [K3sHelmBuilderExtensions.WithHelmValue(IResourceBuilder<HelmReleaseResource>, string, string)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3shelmbuilderextensions/methods.md#withhelmvalue-iresourcebuilder-helmreleaseresource-string-string) for individual key/value pairs or [K3sHelmBuilderExtensions.WithHelmValuesFile(IResourceBuilder<HelmReleaseResource>, string)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3shelmbuilderextensions/methods.md#withhelmvaluesfile-iresourcebuilder-helmreleaseresource-string) to supply a full YAML values file.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withhelmvalue"></a>
<a id="withhelmvalue-iresourcebuilder-helmreleaseresource-string-string"></a>

## WithHelmValue(IResourceBuilder<HelmReleaseResource>, string, string)

- Name: `WithHelmValue(IResourceBuilder<HelmReleaseResource>, string, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<HelmReleaseResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d479e13473b1d29d06b974f144a0049289a3cb5c/src/CommunityToolkit.Aspire.Hosting.K3s/K3sBuilderExtensions.Helm.cs#L207-L212)

Adds a Helm `--set key=value` override to the release.

```csharp
public static class K3sHelmBuilderExtensions
{
    public static IResourceBuilder<HelmReleaseResource> WithHelmValue(
        this IResourceBuilder<HelmReleaseResource> builder,
        string key,
        string value)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<HelmReleaseResource>`)
  The Helm release resource builder.
- `key` (`string`)
  The Helm value path using dot notation, e.g. `server.service.type`. If the same key is set more than once, the last call wins.
- `value` (`string`)
  The value to assign.

## Returns

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

## Exceptions

- `ArgumentNullException` -- `builder`, `key`, or `value` is `null`.

## Remarks

Helm `--set` metacharacters ( `,`, `{`, `}`, `\`) in `key` or `value` are automatically escaped. For values that contain these characters in ways Helm cannot represent safely, use [K3sHelmBuilderExtensions.WithHelmValuesFile(IResourceBuilder<HelmReleaseResource>, string)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3shelmbuilderextensions/methods.md#withhelmvaluesfile-iresourcebuilder-helmreleaseresource-string) instead.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withhelmvaluesfile"></a>
<a id="withhelmvaluesfile-iresourcebuilder-helmreleaseresource-string"></a>

## WithHelmValuesFile(IResourceBuilder<HelmReleaseResource>, string)

- Name: `WithHelmValuesFile(IResourceBuilder<HelmReleaseResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<HelmReleaseResource>`
- Source: [GitHub](https://github.com/CommunityToolkit/Aspire/blob/d479e13473b1d29d06b974f144a0049289a3cb5c/src/CommunityToolkit.Aspire.Hosting.K3s/K3sBuilderExtensions.Helm.cs#L168-L178)

Supplies a YAML values file to the Helm release ( `--values`).

```csharp
public static class K3sHelmBuilderExtensions
{
    public static IResourceBuilder<HelmReleaseResource> WithHelmValuesFile(
        this IResourceBuilder<HelmReleaseResource> builder,
        string path)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<HelmReleaseResource>`)
  The Helm release resource builder.
- `path` (`string`)
  Path to the YAML values file on the host. Relative paths are resolved against the AppHost project directory. Call this method multiple times to supply additional files; they are applied in declaration order and later files win for duplicate keys.

## Returns

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

## Exceptions

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

## Remarks

Use this method for structured overrides -- particularly values containing commas, braces, or backslashes that cannot be safely expressed with [K3sHelmBuilderExtensions.WithHelmValue(IResourceBuilder<HelmReleaseResource>, string, string)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3shelmbuilderextensions/methods.md#withhelmvalue-iresourcebuilder-helmreleaseresource-string-string). Values files are applied before `--set` flags, so [K3sHelmBuilderExtensions.WithHelmValue(IResourceBuilder<HelmReleaseResource>, string, string)](/reference/api/csharp/communitytoolkit.aspire.hosting.k3s/k3shelmbuilderextensions/methods.md#withhelmvalue-iresourcebuilder-helmreleaseresource-string-string) always takes precedence.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.