k8s

Documentation

Overview

Package k8s spins up a Kubernetes cluster for testing.

Index

• Variables
• func CreateObjects(ctx context.Context, cli client.Client, objs ...client.Object) (err error)
• func ReadObjects(r io.Reader, cli client.Client) ([]client.Object, error)
• func ReadUnstructuredObjects(r io.Reader) ([]*unstructured.Unstructured, error)
• func Wait(ctx context.Context, l log.Logger, check func() error) error
• func WaitReady(ctx context.Context, cli client.Client, obj client.Object, bc backoff.Config) error
• type Cluster
  • func NewCluster(ctx context.Context, o Options) (cluster *Cluster, err error)
  • func (c *Cluster) Client() client.Client
  • func (c *Cluster) GetConfig() *rest.Config
  • func (c *Cluster) GetHTTPAddr() string
  • func (c *Cluster) PushImages(images ...string) error
  • func (c *Cluster) Stop()
• type Options
• type ResourceSet
  • func NewResourceSet(l log.Logger, cluster *Cluster) *ResourceSet
  • func (rs *ResourceSet) Add(ctx context.Context, r io.Reader) error
  • func (rs *ResourceSet) AddFile(ctx context.Context, filename string) error
  • func (rs *ResourceSet) Stop()

Variables

var DefaultBackoff = backoff.Config{
	MinBackoff: 100 * time.Millisecond,
	MaxBackoff: 1 * time.Second,
}

DefaultBackoff is a default backoff config that retries forever until ctx is canceled.

Functions

func CreateObjects

func CreateObjects(ctx context.Context, cli client.Client, objs ...client.Object) (err error)

CreateObjects will create the provided set of objects. If any object couldn't be created, an error will be returned and created objects will be deleted.

func ReadObjects

func ReadObjects(r io.Reader, cli client.Client) ([]client.Object, error)

ReadObjects will read the set of objects from r and convert them into client.Object based on the scheme of the provided Kubernetes client.

The data of r may be YAML or JSON.

func ReadUnstructuredObjects

func ReadUnstructuredObjects(r io.Reader) ([]*unstructured.Unstructured, error)

ReadUnstructuredObjects will read the set of objects from r as unstructured objects.

func Wait

func Wait(ctx context.Context, l log.Logger, check func() error) error

Wait calls done until ctx is caneled or check returns nil. Returns an error if ctx is canceled.

func WaitReady

func WaitReady(ctx context.Context, cli client.Client, obj client.Object, bc backoff.Config) error

WaitReady will return with no error if obj becomes ready before ctx cancels or the backoff fails.

obj may be one of: DaemonSet, StatefulSet, Deployment, Pod. obj must have namespace and name set so it can be found. obj will be updated with the state of the object in the cluster as WaitReady runs.

The final state of the object will be returned when it is ready.

Types

type Cluster

type Cluster struct {
	// contains filtered or unexported fields
}

Cluster is a Kubernetes cluster that runs inside of a k3s Docker container. Call GetConfig to retrieve a Kubernetes *rest.Config to use to connect to the cluster.

Cluster also runs an NGINX ingress controller which is exposed to the host. Call GetHTTPAddr to get the address for making requests against the server.

Set K8S_USE_DOCKER_NETWORK in your environment variables if you are running tests from inside of a Docker container. This environment variable configures the k3s Docker container to join the same network as the container tests are running in. When this environment variable isn't set, the exposed ports on the Docker host are used for cluster communication.

Note that k3s uses containerd as its runtime, which means local Docker images are not immediately available for use. To push local images to a container, call PushImages. It's recommended that tests use image names that are not available on Docker Hub to avoid accidentally testing against the wrong image.

Cluster should be stopped by calling Stop, otherwise running Docker containers will leak.

func NewCluster

func NewCluster(ctx context.Context, o Options) (cluster *Cluster, err error)

NewCluster creates a new Cluster. NewCluster won't return with success until the cluster is running, but things like the ingress controller might not be running right away. You should never assume that any resource in the cluster is running and utilize exponential backoffs to allow time for things to spin up.

func (*Cluster) Client

func (c *Cluster) Client() client.Client

Client returns the Kubernetes client for this Cluster. Client is handling objects registered to the Scheme passed to Options when creating the cluster.

func (*Cluster) GetConfig

func (c *Cluster) GetConfig() *rest.Config

GetConfig returns a *rest.Config that can be used to connect to the Kubernetes cluster. The returned Config is a copy and is safe for modification.

func (*Cluster) GetHTTPAddr

func (c *Cluster) GetHTTPAddr() string

GetHTTPAddr returns the host:port address that can be used to connect to the cluster's NGINX server.

func (*Cluster) PushImages

func (c *Cluster) PushImages(images ...string) error

PushImages push images from the local Docker host into the Cluster. If the specified image does not have a tag, `:latest` is assumed.

func (*Cluster) Stop

func (c *Cluster) Stop()

Stop shuts down and deletes the cluster. Stop must be called to clean up created Docker resources.

type Options

type Options struct {
	// Scheme is the Kubernetes scheme used for the generated Kubernetes client.
	// If nil, a generated scheme that contains all known Kubernetes API types
	// will be generated.
	Scheme *runtime.Scheme
}

Options control creation of a cluster.

type ResourceSet

type ResourceSet struct {
	// contains filtered or unexported fields
}

ResourceSet deploys a set of temporary objects to a k8s test cluster and deletes them when Stop is called.

func NewResourceSet

func NewResourceSet(l log.Logger, cluster *Cluster) *ResourceSet

NewResourceSet returns a new resource set.

func (*ResourceSet) Add

func (rs *ResourceSet) Add(ctx context.Context, r io.Reader) error

Add will read from r and deploy the resources into the cluster.

func (*ResourceSet) AddFile

func (rs *ResourceSet) AddFile(ctx context.Context, filename string) error

AddFile will open filename and deploy it into the cluster.

func (*ResourceSet) Stop

func (rs *ResourceSet) Stop()

Stop removes deployed resources from the cluster.