README
¶
Gnomock Lightweight Kubernetes (k3s)
Gnomock Lightweight Kubernetes (k3s) is a Gnomock preset for running tests against a real lightweight kubernetes cluster (k3s), without mocks.
This preset primarily aims to support K3s versions based the active Kubernetes releases. At the time of writing this is:
| Version | Kubernetes and orlangure/gnomock EOL |
|---|---|
| v1.27.x | 2024-06-28 |
| v1.26.x | 2024-02-28 |
| v1.25.x | 2023-10-28 |
| v1.24.x | 2023-07-28 |
Other versions may still work, but no active support will be given for them.
package k3s_test
import (
"context"
"testing"
"github.com/orlangure/gnomock"
"github.com/orlangure/gnomock/preset/k3s"
"github.com/stretchr/testify/require"
v1 "k8s.io/api/core/v1"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"k8s.io/client-go/kubernetes"
)
func TestPreset(t *testing.T) {
t.Parallel()
p := k3s.Preset()
c, err := gnomock.Start(
p,
gnomock.WithContainerName("k3s"),
gnomock.WithDebugMode(),
)
require.NoError(t, err)
defer func() {
require.NoError(t, gnomock.Stop(c))
}()
kubeconfig, err := k3s.Config(c)
require.NoError(t, err)
client, err := kubernetes.NewForConfig(kubeconfig)
require.NoError(t, err)
ctx := context.Background()
pods, err := client.CoreV1().Pods(metav1.NamespaceDefault).List(ctx, metav1.ListOptions{})
require.NoError(t, err)
require.Empty(t, pods.Items)
pod := &v1.Pod{
ObjectMeta: metav1.ObjectMeta{
Name: "gnomock",
Namespace: metav1.NamespaceDefault,
},
Spec: v1.PodSpec{
Containers: []v1.Container{
{
Name: "gnomock",
Image: "docker.io/orlangure/gnomock-test-image",
},
},
RestartPolicy: v1.RestartPolicyNever,
},
}
_, err = client.CoreV1().Pods(metav1.NamespaceDefault).Create(ctx, pod, metav1.CreateOptions{})
require.NoError(t, err)
pods, err = client.CoreV1().Pods(metav1.NamespaceDefault).List(ctx, metav1.ListOptions{})
require.NoError(t, err)
require.Len(t, pods.Items, 1)
require.Equal(t, "gnomock", pods.Items[0].Name)
}
Documentation
¶
Overview ¶
Package k3s provides a Gnomock Preset for lightweight kubernetes (k3s). This preset by no means should be used in any kind of deployment, and no other presets are supposed to be deployed in it. The goal of this preset is to allow easier testing of Kubernetes automation tools.
This preset uses the `docker.io/rancher/k3s` image on Docker Hub as described by the [K3s documentation](https://docs.k3s.io/advanced#running-k3s-in-docker.)
> ```bash > $ docker run \ > --privileged \ > --name k3s-server-1 \ > --hostname k3s-server-1 \ > -p 6443:6443 \ > -d rancher/k3s:v1.24.10-k3s1 \ > server > ```
Please make sure to pick a version here: https://hub.docker.com/r/rancher/k3s/tags.
Keep in mind that k3s runs in a single docker container, meaning it might be limited in memory, CPU and storage. Also remember that this cluster always runs on a single node.
To connect to this cluster, use `Config` function that can be used together with Kubernetes client for Go, or `ConfigBytes` that can be saved as `kubeconfig` file and used by `kubectl`.
Index ¶
Constants ¶
const ( // KubeConfigPortName is the name of the kubeconfig port that serves the // `kubeconfig.yaml`. KubeConfigPortName = "kubeconfig" )
Variables ¶
This section is empty.
Functions ¶
func Config ¶
Config returns `*rest.Config` instance of Kubernetes client-go package. This config can be used to create a new client that will work against k3s cluster running in the provided container.
func ConfigBytes ¶
ConfigBytes returns file contents of kubeconfig file that should be used to connect to the cluster running in the provided container.
Types ¶
type Option ¶
type Option func(*P)
Option is an optional configuration of this Gnomock preset. Use available Options to configure the container.
func WithDynamicPort ¶ added in v0.27.0
func WithDynamicPort() Option
WithDynamicPort configures the preset to find and use a dynamic (free) port for k3s API access from the host. The kubeconfig is replaced with the container host port so local Kubernetes clients will still work.
This is preferred to `WithPort` as it does not require a specific host port to be available.
func WithPort
deprecated
Deprecated: WithPort allows to use a custom port for k3s API access instead of the default one. If no custom port is provided, port 48443 is used instead.
Please make sure that whichever port you choose to use (including the default) is available on the host system. Otherwise this container won't start.
This option and its affects has been kept as is for backward compatibility. We recommend using `WithDynamicPort()` instead as it does not require a static port to be available on the host.
type P ¶
type P struct {
Version string `json:"version"`
// Port is the API port for K3s to listen on.
Port int
// UseDynamicPort instructs the preset to use a dynamic host port instead of
// a static one.
UseDynamicPort bool
// K3sServerFlags are additional k3s server flags added by options.
K3sServerFlags []string
}
P is a Gnomock Preset implementation of lightweight kubernetes (k3s).
func (*P) Ports ¶
func (p *P) Ports() gnomock.NamedPorts
Ports returns ports that should be used to access this container.
Source Files