Skip to content


Not available until the next release of testcontainers-go main


The Testcontainers module for K3s.

Adding this module to your project dependencies

Please run the following command to add the K3s module to your Go dependencies:

go get

Usage example

Module reference

The K3s module exposes one entrypoint function to create the K3s container, and this function receives two parameters:

func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*K3sContainer, error)
  • context.Context, the Go context.
  • testcontainers.ContainerCustomizer, a variadic argument for passing options.

Container Ports

These are the ports used by the K3s container:

defaultKubeSecurePort     = "6443/tcp"
defaultRancherWebhookPort = "8443/tcp"

Container Options

When starting the K3s container, you can pass options in a variadic way to configure it.


If you need to set a different K3s Docker image, you can use testcontainers.WithImage with a valid Docker image for K3s. E.g. testcontainers.WithImage("").

Wait Strategies

If you need to set a different wait strategy for K3s, you can use testcontainers.WithWaitStrategy with a valid wait strategy for K3s.


The default deadline for the wait strategy is 60 seconds.

At the same time, it's possible to set a wait strategy and a custom deadline with testcontainers.WithWaitStrategyAndDeadline.

Docker type modifiers

If you need an advanced configuration for K3s, you can leverage the following Docker type modifiers:

  • testcontainers.WithConfigModifier
  • testcontainers.WithHostConfigModifier
  • testcontainers.WithEndpointSettingsModifier

Please read the Create containers: Advanced Settings documentation for more information.

Container Methods

The K3s container exposes the following methods:


The GetKubeConfig method returns the K3s cluster's kubeconfig, including the server URL, to be used for connecting to the Kubernetes Rest Client API using a Kubernetes client. It'll be returned in the format of []bytes.

kubeConfigYaml, err := container.GetKubeConfig(ctx)
if err != nil {
    t.Fatalf("failed to get kube-config : %s", err)