Aspirerelease/17.0
Watch Aspire live streamsDocsTry Aspire

K3sClusterResource

Handle
📦 CommunityToolkit.Aspire.Hosting.K3s v13.6.1

Represents a k3s Kubernetes cluster running as a privileged container resource. Injects the cluster's kubeconfig into a dependent resource. - -

type K3sClusterResource interface {
ExpressionValue
IComputeResource
Resource
ResourceWithArgs
ResourceWithConnectionString
ResourceWithEndpoints
ResourceWithEnvironment
ResourceWithWaitSupport
}

Properties

propertyApiEndpointEndpointReferenceget
Gets the endpoint reference for the k3s API server (port 6443).
ApiEndpoint() EndpointReference
propertyConnectionStringEnvironmentVariable*stringget
Overrides the default ConnectionStrings__ prefix so Aspire injects KUBECONFIG.
ConnectionStringEnvironmentVariable() (*string, error)
propertyConnectionStringExpression*ReferenceExpressionget
Manifest expression for the local kubeconfig path.
ConnectionStringExpression() *ReferenceExpression

Methods

methodAddHelmReleasebuilder
Installs a Helm chart into the k3s cluster.
AddHelmRelease(
name string,
chart string,
options ...*AddHelmReleaseOptions,
) HelmReleaseResource
namestringThe Aspire resource name; also used as the Helm release name passed to helm upgrade --install.
chartstringThe 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.
options...*AddHelmReleaseOptionsOptional settings, described under Options.

Optional parameters are passed in a trailing options ...*AddHelmReleaseOptions argument.

Repo*stringOptional Helm repository URL, e.g. https://argoproj.github.io/argo-helm. When provided, the repo is added and updated before installation.
Version*stringOptional chart version to pin, e.g. 7.8.0. When null the latest version available in the repository is installed.
Namespace*stringThe Kubernetes namespace to install the release into. The namespace is created automatically if it does not exist. Defaults to default.
HelmReleaseResource

A builder for the HelmReleaseResource.

Returns a handle; failures surface later via Err().

methodAddK8sManifestbuilder
Applies Kubernetes YAML manifests or a Kustomize overlay to the cluster.
AddK8sManifest(
name string,
path string,
) K8sManifestResource
namestringThe Aspire resource name for this manifest application.
pathstringPath to a single .yaml/.yml file, a directory of YAML files, or a Kustomize overlay directory (containing kustomization.yaml). Relative paths are resolved against the AppHost project directory.
K8sManifestResource

A builder for the K8sManifestResource.

Returns a handle; failures surface later via Err().

methodAddServiceEndpointbuilder
Exposes a Kubernetes Service from the cluster as an Aspire endpoint resource.
AddServiceEndpoint(
name string,
serviceName string,
servicePort float64,
options ...*AddServiceEndpointOptions,
) K3sServiceEndpointResource
namestringThe Aspire resource name for this endpoint.
serviceNamestringThe name of the Kubernetes Service to forward, as it appears in kubectl get svc.
servicePortfloat64The port number declared on the Kubernetes Service (the port field, not targetPort). Must be in the range 1–65535.
options...*AddServiceEndpointOptionsOptional settings, described under Options.

Optional parameters are passed in a trailing options ...*AddServiceEndpointOptions argument.

Namespace*stringThe Kubernetes namespace that contains the Service. Defaults to default.
Scheme*stringThe URL scheme (http or https) for the injected environment variable. When null (the default), the scheme is inferred from the port: ports 443 and 8443 use https, all others use http.
K3sServiceEndpointResource

A builder for the K3sServiceEndpointResource.

Returns a handle; failures surface later via Err().

methodWithAgentCountbuilder
Sets the number of k3s agent (worker) nodes to add to the cluster.
WithAgentCount(count float64) K3sClusterResource
countfloat64The number of agent nodes. Zero or greater. Defaults to 0 (single-node cluster — the server node acts as both control-plane and worker).
K3sClusterResource

The same builder, for chaining.

Returns a handle; failures surface later via Err().

methodWithDataVolumebuilder
Mounts a named Docker volume at the k3s data directory so cluster state persists across AppHost restarts.
WithDataVolume(options ...*WithDataVolumeOptions) K3sClusterResource
options...*WithDataVolumeOptionsOptional settings, described under Options.

Optional parameters are passed in a trailing options ...*WithDataVolumeOptions argument.

Name*stringOptional volume name. When null (the default) a name is generated from the application and resource names.
K3sClusterResource

The same builder, for chaining.

Returns a handle; failures surface later via Err().

Disables a built-in k3s component (--disable=<component>).
WithDisabledComponent(component string) K3sClusterResource
componentstringThe 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.
K3sClusterResource

The same builder, for chaining.

Returns a handle; failures surface later via Err().

methodWithExtraArgbuilder
Appends a raw argument to the k3s server command line.
WithExtraArg(arg string) K3sClusterResource
argstringThe raw argument to append, e.g. --write-kubeconfig-mode=644. Call this method multiple times to append additional arguments.
K3sClusterResource

The same builder, for chaining.

Returns a handle; failures surface later via Err().

methodWithHelmImagebuilder
Overrides the container image used to run helm upgrade --install for all HelmReleaseResource children of this cluster.
WithHelmImage(options ...*WithHelmImageOptions) K3sClusterResource
options...*WithHelmImageOptionsOptional settings, described under Options.

Optional parameters are passed in a trailing options ...*WithHelmImageOptions argument.

Tag*stringImage tag, e.g. 3.18.0. null keeps the current value.
Image*stringImage name, e.g. alpine/helm. null keeps the current value.
Registry*stringRegistry, e.g. docker.io. null keeps the current value.
K3sClusterResource

The same builder, for chaining.

Returns a handle; failures surface later via Err().

methodWithK3sVersionbuilder
Sets the k3s image version used by the cluster server and all its agent nodes.
WithK3sVersion(tag string) K3sClusterResource
tagstringThe k3s container image tag, e.g. v1.32.3-k3s1. Must follow the v{major}.{minor}.{patch}-k3s{n} format.
K3sClusterResource

The same builder, for chaining.

Returns a handle; failures surface later via Err().

methodWithKubectlImagebuilder
Overrides the container image used to run kubectl apply for all K8sManifestResource children of this cluster.
WithKubectlImage(options ...*WithKubectlImageOptions) K3sClusterResource
options...*WithKubectlImageOptionsOptional settings, described under Options.

Optional parameters are passed in a trailing options ...*WithKubectlImageOptions argument.

Tag*stringImage tag, e.g. 1.37.0. null keeps the current value.
Image*stringImage name, e.g. alpine/kubectl. null keeps the current value.
Registry*stringRegistry, e.g. docker.io. null keeps the current value.
K3sClusterResource

The same builder, for chaining.

Returns a handle; failures surface later via Err().

methodWithLifetimebuilder
Sets the container lifetime for the k3s cluster and all its agent nodes.
WithLifetime(lifetime ContainerLifetime) K3sClusterResource
lifetimeContainerLifetimeThe container lifetime to apply.
K3sClusterResource

The same builder, for chaining.

Returns a handle; failures surface later via Err().

methodWithPodSubnetbuilder
Sets the CIDR range for pod IP addresses (--cluster-cidr).
WithPodSubnet(cidr string) K3sClusterResource
cidrstringThe pod subnet in CIDR notation, e.g. 10.42.0.0/16.
K3sClusterResource

The same builder, for chaining.

Returns a handle; failures surface later via Err().

methodWithServiceSubnetbuilder
Sets the CIDR range for Service cluster IPs (--service-cidr).
WithServiceSubnet(cidr string) K3sClusterResource
cidrstringThe service subnet in CIDR notation, e.g. 10.43.0.0/16.
K3sClusterResource

The same builder, for chaining.

Returns a handle; failures surface later via Err().