frameworks: github.com/kubernetes-sig-testing/frameworks/integration Index | Files | Directories

package integration

import "github.com/kubernetes-sig-testing/frameworks/integration"

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

If you want to test a kubernetes client against the latest kubernetes APIServer and Etcd, you can use `./scripts/download-binaries.sh` to download APIServer and Etcd binaries for your platform. Then 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/`.

For convenience this framework ships with `${FRAMEWORK_DIR}/scripts/download-binaries.sh` which can be used to download pre-compiled versions of the needed binaries and place them in the default location (`${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

Package Files

apiserver.go control_plane.go doc.go etcd.go kubectl.go

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 explicitely 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 explicitely copied here, we don't want to allow users to change the internal ones.

type APIServer Uses

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

    // 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 caluclated 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 Uses

func (s *APIServer) Start() error

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

func (*APIServer) Stop Uses

func (s *APIServer) Stop() error

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

type ControlPlane Uses

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 Uses

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

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

func (*ControlPlane) KubeCtl Uses

func (f *ControlPlane) KubeCtl() *KubeCtl

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

func (*ControlPlane) Start Uses

func (f *ControlPlane) Start() error

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

func (*ControlPlane) Stop Uses

func (f *ControlPlane) Stop() error

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

type Etcd Uses

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 caluclated 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 Uses

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 Uses

func (e *Etcd) Stop() error

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

type KubeCtl Uses

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 Uses

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.

Directories

PathSynopsis
internal
internal/integration_testsPackage integrarion_tests is holding the integration tests to run against the framework.

Package integration imports 7 packages (graph). Updated 2018-07-14. Refresh now. Tools for package owners.