Documentation ¶
Overview ¶
Package virtuakube sets up virtual Kubernetes clusters for tests.
The top-level object is a Universe. Everything else exists within a Universe, and is cleaned up when the Universe is closed. Within a Universe, you can create either bare VMs (using universe.NewVM), or Kubernetes clusters (using universe.NewCluster).
Universes ¶
A universe requires a directory on disk to store its state. You get a universe either by calling Create to make a new blank one, or by calling Open to reuse an existing one.
There are three ways of closing a universe. Calling Destroy wipes all the universe's state. Save snapshots and preserve all current resources, such that the next call to Open will resume the universe exactly as it was when last saved. Close preserves the universe, but rewinds its state to the last time it was saved, or to its pristine post-creation state if it was never saved.
A typical use of virtuakube in tests is to do expensive setup ahead of time: use Create to make a new universe, then create and configure resources within, and finally call Save to snapshot it. Then, tests can simply Open this universe to get a fully working system immediately. When each test is done, they can Close the universe to undo all the changes that happened during the test, ready for the next test to Open.
VMs ¶
VMs have a preset form that can be customized somewhat, but not fundamentally changed.
Each VM has a single virtual disk, which is a copy-on-write fork of a base image. You can build base images with universe.NewImage.
Each VM gets two network interfaces. The first provides internet access, and the second connects to a virtual LAN shared by all VMs in the same Universe.
Network access to VMs from the host machine is only possible via port forwards, which are specified in the VM's configuration at creation time. Use vm.ForwardedPort to find out the local port to use to reach a given port on the VM.
The VM type provides some helpers for running commands and reading/writing files on the VM.
Kubernetes Clusters ¶
Clusters consist of one control plane VM, and a configurable number of additional worker VMs. Once created, the Cluster type has helpers to retrieve a kubeconfig file to talk to the cluster, a Go kubernetes client connected to the cluster, and the port to talk to the in-cluster registry to push images.
VM Images ¶
VM images belong to a universe, and can be created with NewImage. NewImage accepts customization functions to do things like install extra packages, or configure services that all VMs using the image will need.
If you customize your own VM image, it must conform to the following conventions for virtuakube to function correctly.
The VM should autoconfigure the first network interface (ens3) using DHCP. Other ens* network interfaces should be left unconfigured. The `ip` tool must be installed so that virtuakube can configure those other interfaces.
The VM should disable any kind of time synchronization, and rely purely on the VM's local virtual clock. VMs may spend hours or more suspended, and to avoid issues associated with timejumps on resume, virtuakube wants to maintain the illusion that no time has passed since suspend.
If you want to use NewCluster with your VM image, the VM must have docker, kubectl and kubeadm preinstalled. Dependencies and prerequisites must be satisfied such that `kubeadm init` produces a working single-node cluster. Virtuakube includes stock customization functions to install Kubernetes prerequisites, and to pre-pull the Docker images for faster cluster startup when NewCluster is called.
Index ¶
- func CustomizeInstallK8s(v *VM) error
- func CustomizePreloadK8sImages(v *VM) error
- func CustomizeScript(path string) func(*VM) error
- type Cluster
- func (c *Cluster) ApplyManifest(bs []byte) error
- func (c *Cluster) Controller() *VM
- func (c *Cluster) Kubeconfig() string
- func (c *Cluster) KubernetesClient() *kubernetes.Clientset
- func (c *Cluster) Name() string
- func (c *Cluster) Nodes() []*VM
- func (c *Cluster) NodesReady() (bool, error)
- func (c *Cluster) PushImages(images ...string) error
- func (c *Cluster) Start() error
- func (c *Cluster) WaitFor(ctx context.Context, test func() (bool, error)) error
- type ClusterConfig
- type Image
- type ImageConfig
- type ImageCustomizeFunc
- type Network
- type NetworkConfig
- type Universe
- func (u *Universe) Close() error
- func (u *Universe) Cluster(name string) *Cluster
- func (u *Universe) Clusters() []*Cluster
- func (u *Universe) Command(command string, args ...string) *exec.Cmd
- func (u *Universe) Destroy() error
- func (u *Universe) ImportImage(name, path string) error
- func (u *Universe) NewCluster(cfg *ClusterConfig) (*Cluster, error)
- func (u *Universe) NewImage(cfg *ImageConfig) error
- func (u *Universe) NewNetwork(cfg *NetworkConfig) error
- func (u *Universe) NewVM(cfg *VMConfig) (*VM, error)
- func (u *Universe) Save(snapshotName string) error
- func (u *Universe) Snapshots() []string
- func (u *Universe) VM(name string) *VM
- func (u *Universe) VMs() []*VM
- func (u *Universe) Wait(ctx context.Context) error
- type UniverseConfig
- type VM
- func (v *VM) Close() error
- func (v *VM) Dial(network, addr string) (net.Conn, error)
- func (v *VM) ForwardedPort(dst int) int
- func (v *VM) Hostname() string
- func (v *VM) IPv4(network string) net.IP
- func (v *VM) IPv6(network string) net.IP
- func (v *VM) Networks() []string
- func (v *VM) ReadFile(path string) ([]byte, error)
- func (v *VM) Run(command string) ([]byte, error)
- func (v *VM) RunMultiple(commands ...string) error
- func (v *VM) RunWithInput(command string, stdin io.Reader) ([]byte, error)
- func (v *VM) Start() error
- func (v *VM) Wait(ctx context.Context) error
- func (v *VM) WriteFile(path string, bs []byte) error
- type VMConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CustomizeInstallK8s ¶
CustomizeInstallK8s is a build customization function that installs Docker and Kubernetes prerequisites, as required for NewCluster to function.
func CustomizePreloadK8sImages ¶
CustomizePreloadK8sImages is a build customization function that pre-pulls all the Docker images needed to fully initialize a Kubernetes cluster.
func CustomizeScript ¶
CustomizeScript is a build customization function that executes the script at path on a VM running the disk image being built.
Types ¶
type Cluster ¶
type Cluster struct {
// contains filtered or unexported fields
}
Cluster is a virtual Kubernetes cluster.
func (*Cluster) ApplyManifest ¶
func (*Cluster) Controller ¶
Controller returns the VM for the cluster controller node.
func (*Cluster) Kubeconfig ¶
func (*Cluster) KubernetesClient ¶
func (c *Cluster) KubernetesClient() *kubernetes.Clientset
KubernetesClient returns a kubernetes client connected to the cluster.
func (*Cluster) NodesReady ¶
NodesReady returns true if all nodes in the cluster are in the Ready state.
func (*Cluster) PushImages ¶
PushImages extracts the named images from the host's docker daemon, and pushes them to the docker daemons on all nodes in the cluster.
type ClusterConfig ¶
type ClusterConfig struct { Name string // NumNodes is the number of Kubernetes worker nodes to run. NumNodes int // The VMConfig template to use when creating cluster VMs. The // first configured VM network will be used for Kubernetes control // traffic. VMConfig *VMConfig }
ClusterConfig is the configuration for a virtual Kubernetes cluster.
type Image ¶
type Image struct {
// contains filtered or unexported fields
}
Image is a VM disk base image.
type ImageConfig ¶
type ImageConfig struct { Name string CustomizeFuncs []ImageCustomizeFunc NoKVM bool }
ImageConfig is the build configuration for an Image.
type ImageCustomizeFunc ¶
ImageCustomizeFunc is a function that applies customizations to a VM that's being built by NewImage.
type NetworkConfig ¶
type NetworkConfig struct {
Name string
}
type Universe ¶
type Universe struct {
// contains filtered or unexported fields
}
A Universe is a virtual sandbox and its associated resources.
func Create ¶
func Create(dir string, runtimecfg *UniverseConfig) (*Universe, error)
Create creates a new empty Universe in dir. The directory must not already exist.
func Open ¶
func Open(dir string, snapshot string, runtimecfg *UniverseConfig) (*Universe, error)
Open opens the existing Universe in dir, and resumes from snapshot.
func (*Universe) Close ¶
Close closes the universe, discarding all changes since the last call to Save.
func (*Universe) Cluster ¶
Cluster returns the Cluster with the given name, or nil if no such Cluster exists in the universe.
func (*Universe) Destroy ¶
Destroy closes the universe and recursively deletes the universe directory.
func (*Universe) ImportImage ¶
func (*Universe) NewCluster ¶
func (u *Universe) NewCluster(cfg *ClusterConfig) (*Cluster, error)
NewCluster creates an unstarted Kubernetes cluster with the given configuration.
func (*Universe) NewImage ¶
func (u *Universe) NewImage(cfg *ImageConfig) error
NewImage builds a VM disk image using the given config.
func (*Universe) NewNetwork ¶
func (u *Universe) NewNetwork(cfg *NetworkConfig) error
func (*Universe) Save ¶
Save snapshots the current state of VMs and clusters, then closes the universe.
type UniverseConfig ¶
type UniverseConfig struct { // If non-nil, all commands executed on VMs and during image // building are logged to this writer, along with their // stdout/stderr. CommandLog io.Writer // Whether VMs should have a GUI. Useful for debugging Virtuakube // itself. VMGraphics bool // Make subprocesses immune to ^C, to enable interactive control. Interactive bool // Don't use any privileged hardware acceleration for VMs. Will // run much slower, but 100% in userspace. NoAcceleration bool }
UniverseConfig contains the ephemeral runtime settings for the universe. A nil UniverseConfig is equivalent to the zero value.
type VM ¶
type VM struct {
// contains filtered or unexported fields
}
VM is a virtual machine.
func (*VM) Close ¶
Close shuts down the VM, reverting all changes since the universe was last saved.
func (*VM) ForwardedPort ¶
ForwardedPort returns the port on localhost that maps to the given port on the VM.
func (*VM) Hostname ¶
Hostname returns the configured hostname of the VM. It might be different from the VM's actual hostname if its hostname was changed after boot by something other than virtuakube.
func (*VM) RunMultiple ¶
RunMultiple runs all given commands sequentially. It stops at the first unsuccessful command and returns its error.