integration

README

Integration Testing Framework

This package has been moved from https://github.com/kubernetes-sigs/testing_frameworks/tree/master/integration.

A framework for integration testing components of kubernetes. This framework is intended to work properly both in CI, and on a local dev machine. It therefore explicitly supports both Linux and Darwin.

For detailed documentation see the .

Documentation

Overview

Package integration implements an integration testing framework for kubernetes.

It provides components for standing up a kubernetes API, against which you can test a kubernetes client, or other kubernetes components. The lifecycle of the components needed to provide this API is managed by this framework.

Quickstart

Add something like the following to your tests:

cp := &integration.ControlPlane{}
cp.Start()
kubeCtl := cp.KubeCtl()
stdout, stderr, err := kubeCtl.Run("get", "pods")
// You can check on err, stdout & stderr and build up
// your tests
cp.Stop()

Components

Currently the framework provides the following components:

ControlPlane: The ControlPlane wraps Etcd & APIServer (see below) and wires them together correctly. A ControlPlane can be stopped & started and can provide the URL to connect to the API. The ControlPlane can also be asked for a KubeCtl which is already correctly configured for this ControlPlane. The ControlPlane is a good entry point for default setups.

Etcd: Manages an Etcd binary, which can be started, stopped and connected to. By default Etcd will listen on a random port for http connections and will create a temporary directory for its data. To configure it differently, see the Etcd type documentation below.

APIServer: Manages an Kube-APIServer binary, which can be started, stopped and connected to. By default APIServer will listen on a random port for http connections and will create a temporary directory to store the (auto-generated) certificates. To configure it differently, see the APIServer type documentation below.

KubeCtl: Wraps around a `kubectl` binary and can `Run(...)` arbitrary commands against a kubernetes control plane.

Binaries

Etcd, APIServer & KubeCtl use the same mechanism to determine which binaries to use when they get started.

1. If the component is configured with a `Path` the framework tries to run that binary. For example:

myEtcd := &Etcd{
	Path: "/some/other/etcd",
}
cp := &integration.ControlPlane{
	Etcd: myEtcd,
}
cp.Start()

2. If the Path field on APIServer, Etcd or KubeCtl is left unset and an environment variable named `TEST_ASSET_KUBE_APISERVER`, `TEST_ASSET_ETCD` or `TEST_ASSET_KUBECTL` is set, its value is used as a path to the binary for the APIServer, Etcd or KubeCtl.

3. If neither the `Path` field, nor the environment variable is set, the framework tries to use the binaries `kube-apiserver`, `etcd` or `kubectl` in the directory `${FRAMEWORK_DIR}/assets/bin/`.

Arguments for Etcd and APIServer

Those components will start without any configuration. However, if you want or need to, you can override certain configuration -- one of which are the arguments used when calling the binary.

When you choose to specify your own set of arguments, those won't be appended to the default set of arguments, it is your responsibility to provide all the arguments needed for the binary to start successfully.

However, the default arguments for APIServer and Etcd are exported as `APIServerDefaultArgs` and `EtcdDefaultArgs` from this package. Treat those variables as read-only constants. Internally we have a set of default arguments for defaulting, the `APIServerDefaultArgs` and `EtcdDefaultArgs` are just copies of those. So when you override them you loose access to the actual internal default arguments, but your override won't affect the defaulting.

All arguments are interpreted as go templates. Those templates have access to all exported fields of the `APIServer`/`Etcd` struct. It does not matter if those fields where explicitly set up or if they were defaulted by calling the `Start()` method, the template evaluation runs just before the binary is executed and right after the defaulting of all the struct's fields has happened.

// When you want to append additional arguments ...
etcd := &Etcd{
	// Additional custom arguments will appended to the set of default
	// arguments
	Args:    append(EtcdDefaultArgs, "--additional=arg"),
	DataDir: "/my/special/data/dir",
}

// When you want to use a custom set of arguments ...
etcd := &Etcd{
	// Only custom arguments will be passed to the binary
	Args:    []string{"--one=1", "--two=2", "--three=3"},
	DataDir: "/my/special/data/dir",
}

Index

• Variables
• type APIServer
  • func (s *APIServer) Start() error
  • func (s *APIServer) Stop() error
• type ControlPlane
  • func (f *ControlPlane) APIURL() *url.URL
  • func (f *ControlPlane) KubeCtl() *KubeCtl
  • func (f *ControlPlane) RESTClientConfig() (*rest.Config, error)
  • func (f *ControlPlane) Start() error
  • func (f *ControlPlane) Stop() error
• type Etcd
  • func (e *Etcd) Start() error
  • func (e *Etcd) Stop() error
• type KubeCtl
  • func (k *KubeCtl) Run(args ...string) (stdout, stderr io.Reader, err error)

Variables

var APIServerDefaultArgs = append([]string{}, internal.APIServerDefaultArgs...)

APIServerDefaultArgs exposes the default args for the APIServer so that you can use those to append your own additional arguments.

The internal default arguments are explicitly copied here, we don't want to allow users to change the internal ones.

var EtcdDefaultArgs = append([]string{}, internal.EtcdDefaultArgs...)

EtcdDefaultArgs exposes the default args for Etcd so that you can use those to append your own additional arguments.

The internal default arguments are explicitly copied here, we don't want to allow users to change the internal ones.

var NewTinyCA = internal.NewTinyCA

NewTinyCA creates a new a tiny CA utility for provisioning serving certs and client certs FOR TESTING ONLY. Don't use this for anything else!

Types

type APIServer

type APIServer struct {
	// URL is the address the ApiServer should listen on for client connections.
	//
	// If this is not specified, we default to a random free port on localhost.
	URL *url.URL

	// SecurePort is the additional secure port that the APIServer should listen on.
	SecurePort int

	// Path is the path to the apiserver binary.
	//
	// If this is left as the empty string, we will attempt to locate a binary,
	// by checking for the TEST_ASSET_KUBE_APISERVER environment variable, and
	// the default test assets directory. See the "Binaries" section above (in
	// doc.go) for details.
	Path string

	// Args is a list of arguments which will passed to the APIServer binary.
	// Before they are passed on, they will be evaluated as go-template strings.
	// This means you can use fields which are defined and exported on this
	// APIServer struct (e.g. "--cert-dir={{ .Dir }}").
	// Those templates will be evaluated after the defaulting of the APIServer's
	// fields has already happened and just before the binary actually gets
	// started. Thus you have access to calculated fields like `URL` and others.
	//
	// If not specified, the minimal set of arguments to run the APIServer will
	// be used.
	Args []string

	// CertDir is a path to a directory containing whatever certificates the
	// APIServer will need.
	//
	// If left unspecified, then the Start() method will create a fresh temporary
	// directory, and the Stop() method will clean it up.
	CertDir string

	// EtcdURL is the URL of the Etcd the APIServer should use.
	//
	// If this is not specified, the Start() method will return an error.
	EtcdURL *url.URL

	// StartTimeout, StopTimeout specify the time the APIServer is allowed to
	// take when starting and stoppping before an error is emitted.
	//
	// If not specified, these default to 20 seconds.
	StartTimeout time.Duration
	StopTimeout  time.Duration

	// Out, Err specify where APIServer should write its StdOut, StdErr to.
	//
	// If not specified, the output will be discarded.
	Out io.Writer
	Err io.Writer
	// contains filtered or unexported fields
}

APIServer knows how to run a kubernetes apiserver.

func (*APIServer) Start

func (s *APIServer) Start() error

Start starts the apiserver, waits for it to come up, and returns an error, if occurred.

func (*APIServer) Stop

func (s *APIServer) Stop() error

Stop stops this process gracefully, waits for its termination, and cleans up the CertDir if necessary.

type ControlPlane

type ControlPlane struct {
	APIServer *APIServer
	Etcd      *Etcd
}

ControlPlane is a struct that knows how to start your test control plane.

Right now, that means Etcd and your APIServer. This is likely to increase in future.

func (*ControlPlane) APIURL

func (f *ControlPlane) APIURL() *url.URL

APIURL returns the URL you should connect to to talk to your API.

func (*ControlPlane) KubeCtl

func (f *ControlPlane) KubeCtl() *KubeCtl

KubeCtl returns a pre-configured KubeCtl, ready to connect to this ControlPlane.

func (*ControlPlane) RESTClientConfig

func (f *ControlPlane) RESTClientConfig() (*rest.Config, error)

RESTClientConfig returns a pre-configured restconfig, ready to connect to this ControlPlane.

func (*ControlPlane) Start

func (f *ControlPlane) Start() error

Start will start your control plane processes. To stop them, call Stop().

func (*ControlPlane) Stop

func (f *ControlPlane) Stop() error

Stop will stop your control plane processes, and clean up their data.

type Etcd

type Etcd struct {
	// URL is the address the Etcd should listen on for client connections.
	//
	// If this is not specified, we default to a random free port on localhost.
	URL *url.URL

	// Path is the path to the etcd binary.
	//
	// If this is left as the empty string, we will attempt to locate a binary,
	// by checking for the TEST_ASSET_ETCD environment variable, and the default
	// test assets directory. See the "Binaries" section above (in doc.go) for
	// details.
	Path string

	// Args is a list of arguments which will passed to the Etcd binary. Before
	// they are passed on, the`y will be evaluated as go-template strings. This
	// means you can use fields which are defined and exported on this Etcd
	// struct (e.g. "--data-dir={{ .Dir }}").
	// Those templates will be evaluated after the defaulting of the Etcd's
	// fields has already happened and just before the binary actually gets
	// started. Thus you have access to calculated fields like `URL` and others.
	//
	// If not specified, the minimal set of arguments to run the Etcd will be
	// used.
	Args []string

	// DataDir is a path to a directory in which etcd can store its state.
	//
	// If left unspecified, then the Start() method will create a fresh temporary
	// directory, and the Stop() method will clean it up.
	DataDir string

	// StartTimeout, StopTimeout specify the time the Etcd is allowed to
	// take when starting and stopping before an error is emitted.
	//
	// If not specified, these default to 20 seconds.
	StartTimeout time.Duration
	StopTimeout  time.Duration

	// Out, Err specify where Etcd should write its StdOut, StdErr to.
	//
	// If not specified, the output will be discarded.
	Out io.Writer
	Err io.Writer
	// contains filtered or unexported fields
}

Etcd knows how to run an etcd server.

func (*Etcd) Start

func (e *Etcd) Start() error

Start starts the etcd, waits for it to come up, and returns an error, if one occoured.

func (*Etcd) Stop

func (e *Etcd) Stop() error

Stop stops this process gracefully, waits for its termination, and cleans up the DataDir if necessary.

type KubeCtl

type KubeCtl struct {
	// Path where the kubectl binary can be found.
	//
	// If this is left empty, we will attempt to locate a binary, by checking for
	// the TEST_ASSET_KUBECTL environment variable, and the default test assets
	// directory. See the "Binaries" section above (in doc.go) for details.
	Path string

	// Opts can be used to configure additional flags which will be used each
	// time the wrapped binary is called.
	//
	// For example, you might want to use this to set the URL of the APIServer to
	// connect to.
	Opts []string
}

KubeCtl is a wrapper around the kubectl binary.

func (*KubeCtl) Run

func (k *KubeCtl) Run(args ...string) (stdout, stderr io.Reader, err error)

Run executes the wrapped binary with some preconfigured options and the arguments given to this method. It returns Readers for the stdout and stderr.