K3sBuilderExtensions Methods

ClassMethods11 members

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

AddK3sCluster(IDistributedApplicationBuilder, string, int?, int?)extensionIResourceBuilder<K3sClusterResource>

Adds a k3s Kubernetes cluster to the distributed application.

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

K3sBuilderExtensions.cs#L67-L268

Parameters

builderIDistributedApplicationBuilderThe distributed application builder.

namestring 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).

apiServerPortint?optional Host port to bind the Kubernetes API server (port 6443) to. When null (the default) a random available port is assigned.

agentCountint?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 on the returned builder.

Returns

IResourceBuilder<K3sClusterResource>A builder for the K3sClusterResource.

Exceptions

ArgumentNullExceptionbuilder 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, K3sBuilderExtensions.WithAgentCount, K3sBuilderExtensions.WithPodSubnet, K3sBuilderExtensions.WithServiceSubnet, K3sBuilderExtensions.WithDisabledComponent, K3sBuilderExtensions.WithExtraArg, K3sBuilderExtensions.WithDataVolume, K3sBuilderExtensions.WithHelmImage, K3sBuilderExtensions.WithKubectlImage, and K3sBuilderExtensions.WithLifetime.

WithAgentCount(IResourceBuilder<K3sClusterResource>, int)extensionIResourceBuilder<K3sClusterResource>

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

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

K3sBuilderExtensions.cs#L464-L475

Parameters

builderIResourceBuilder<K3sClusterResource>The k3s cluster resource builder.

countint 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

ArgumentNullExceptionbuilder is null.

ArgumentOutOfRangeExceptioncount 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 with ContainerLifetime.Persistent to keep agents alive across AppHost restarts and avoid node password hash mismatches.

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

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

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

K3sBuilderExtensions.cs#L427-L438

Parameters

builderIResourceBuilder<K3sClusterResource>The k3s cluster resource builder.

namestring?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

ArgumentNullExceptionbuilder 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.

WithDisabledComponent(IResourceBuilder<K3sClusterResource>, string)extensionIResourceBuilder<K3sClusterResource>

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

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

K3sBuilderExtensions.cs#L373-L376

Parameters

builderIResourceBuilder<K3sClusterResource>The k3s cluster resource builder.

componentstring 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

ArgumentNullExceptionbuilder is null.

ArgumentExceptioncomponent is null or whitespace.

WithExtraArg(IResourceBuilder<K3sClusterResource>, string)extensionIResourceBuilder<K3sClusterResource>

Appends a raw argument to the k3s server command line.

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

K3sBuilderExtensions.cs#L399-L402

Parameters

builderIResourceBuilder<K3sClusterResource>The k3s cluster resource builder.

argstring 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

ArgumentNullExceptionbuilder is null.

ArgumentExceptionarg is null or whitespace.

Remarks

Use K3sBuilderExtensions.WithDisabledComponent or the dedicated CIDR methods when possible. This method is intended for flags that have no dedicated helper.

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

Overrides the container image used to run helm upgrade --install for all HelmReleaseResource children of this cluster.

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

K3sBuilderExtensions.cs#L495-L498

Parameters

builderIResourceBuilder<K3sClusterResource>The k3s cluster resource builder.

tagstring?optionalImage tag, e.g. 3.18.0. null keeps the current value.

imagestring?optionalImage name, e.g. alpine/helm. null keeps the current value.

registrystring?optionalRegistry, e.g. docker.io. null keeps the current value.

Returns

IResourceBuilder<K3sClusterResource>The same builder, for chaining.

Exceptions

ArgumentNullExceptionbuilder is null.

WithK3sVersion(IResourceBuilder<K3sClusterResource>, string)extensionIResourceBuilder<K3sClusterResource>

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

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

K3sBuilderExtensions.cs#L292-L315

Parameters

builderIResourceBuilder<K3sClusterResource>The k3s cluster resource builder.

tagstring 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

ArgumentNullExceptionbuilder is null.

ArgumentExceptiontag 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.

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

Overrides the container image used to run kubectl apply for all K8sManifestResource children of this cluster.

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

K3sBuilderExtensions.cs#L518-L521

Parameters

builderIResourceBuilder<K3sClusterResource>The k3s cluster resource builder.

tagstring?optionalImage tag, e.g. 1.37.0. null keeps the current value.

imagestring?optionalImage name, e.g. alpine/kubectl. null keeps the current value.

registrystring?optionalRegistry, e.g. docker.io. null keeps the current value.

Returns

IResourceBuilder<K3sClusterResource>The same builder, for chaining.

Exceptions

ArgumentNullExceptionbuilder is null.

WithLifetime(IResourceBuilder<K3sClusterResource>, ContainerLifetime)extensionIResourceBuilder<K3sClusterResource>

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

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

K3sBuilderExtensions.cs#L543-L556

Parameters

builderIResourceBuilder<K3sClusterResource>The k3s cluster resource builder.

lifetimeContainerLifetimeThe container lifetime to apply.

Returns

IResourceBuilder<K3sClusterResource>The same builder, for chaining.

Exceptions

ArgumentNullExceptionbuilder 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.

WithPodSubnet(IResourceBuilder<K3sClusterResource>, string)extensionIResourceBuilder<K3sClusterResource>

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

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

K3sBuilderExtensions.cs#L331-L334

Parameters

builderIResourceBuilder<K3sClusterResource>The k3s cluster resource builder.

cidrstringThe pod subnet in CIDR notation, e.g. 10.42.0.0/16.

Returns

IResourceBuilder<K3sClusterResource>The same builder, for chaining.

Exceptions

ArgumentNullExceptionbuilder is null.

ArgumentExceptioncidr is null or whitespace.

WithServiceSubnet(IResourceBuilder<K3sClusterResource>, string)extensionIResourceBuilder<K3sClusterResource>

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

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

K3sBuilderExtensions.cs#L350-L353

Parameters

builderIResourceBuilder<K3sClusterResource>The k3s cluster resource builder.

cidrstringThe service subnet in CIDR notation, e.g. 10.43.0.0/16.

Returns

IResourceBuilder<K3sClusterResource>The same builder, for chaining.

Exceptions

ArgumentNullExceptionbuilder is null.

ArgumentExceptioncidr is null or whitespace.