k3s

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.

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 does not use a well-known docker image like most other presets do. Instead, it uses a custom built and adapted image that runs lightweight Kubernetes (k3s) in a docker container: https://github.com/orlangure/k3s-dind.

Please make sure to pick a version here: https://hub.docker.com/repository/docker/orlangure/k3s.

The following versions include important fixes that prevent this preset from working on recent Linux Kernel versions, please make sure to avoid using older versions for each API level:

• v1.18.19
• v1.19.11
• v1.20.7
• v1.21.1

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

This preset currently doesn't work on arm64 architecture, or on Ubuntu 22.04 (latest supported Ubuntu version is 20.04) due to internal cgroup changes.

Index

• Constants
• func Config(c *gnomock.Container) (*rest.Config, error)
• func ConfigBytes(c *gnomock.Container) (configBytes []byte, err error)
• func Preset(opts ...Option) gnomock.Preset
• type Option
  • func WithPort(port int) Option
  • func WithVersion(version string) Option
• type P
  • func (p *P) Image() string
  • func (p *P) Options() []gnomock.Option
  • func (p *P) Ports() gnomock.NamedPorts

Constants

const (
	KubeconfigPort = "kubeconfig"
)

KubeconfigPort is a port that exposes a single `/kubeconfig` endpoint. It can be used to retrieve a configured kubeconfig file to use to connect to this container using kubectl.

Functions

func Config

func Config(c *gnomock.Container) (*rest.Config, error)

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

func ConfigBytes(c *gnomock.Container) (configBytes []byte, err error)

ConfigBytes returns file contents of kubeconfig file that should be used to connect to the cluster running in the provided container.

func Preset

func Preset(opts ...Option) gnomock.Preset

Preset creates a new Gmomock k3s preset. This preset includes a k3s specific healthcheck function and default k3s image and port. Please note that this preset launches a privileged docker container.

By default, this preset sets up k3s v1.19.3.

Types

type Option

type Option func(*P)

Option is an optional configuration of this Gnomock preset. Use available Options to configure the container.

func WithPort

func WithPort(port int) Option

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.

func WithVersion

func WithVersion(version string) Option

WithVersion sets image version.

type P

type P struct {
	Version string `json:"version"`
	Port    int
}

P is a Gnomock Preset implementation of lightweight kubernetes (k3s).

func (*P) Image

func (p *P) Image() string

Image returns an image that should be pulled to create this container.

func (*P) Options

func (p *P) Options() []gnomock.Option

Options returns a list of options to configure this container.

func (*P) Ports

func (p *P) Ports() gnomock.NamedPorts

Ports returns ports that should be used to access this container.