Documentation
¶
Overview ¶
Package envtest provides libraries for integration testing by starting a local control plane
Control plane binaries (etcd and kube-apiserver) are loaded by default from /usr/local/kubebuilder/bin. This can be overridden by setting the KUBEBUILDER_ASSETS environment variable, or by directly creating a ControlPlane for the Environment to use.
Environment can also be configured to work with an existing cluster, and simply load CRDs and provide client configuration.
Index ¶
- Constants
- Variables
- func CreateCRDs(config *rest.Config, crds []*apiextensionsv1.CustomResourceDefinition) error
- func InstallCRDs(config *rest.Config, options CRDInstallOptions) ([]*apiextensionsv1.CustomResourceDefinition, error)
- func UninstallCRDs(config *rest.Config, options CRDInstallOptions) error
- func WaitForCRDs(config *rest.Config, crds []*apiextensionsv1.CustomResourceDefinition, ...) error
- func WaitForWebhooks(config *rest.Config, ...) error
- type APIServer
- type Arg
- type Arguments
- type AuthenticatedUser
- type Authn
- type CRDInstallOptions
- type ControlPlane
- type Environment
- type Etcd
- type ListenAddr
- type SecureServing
- type User
- type WebhookInstallOptions
Constants ¶
const ( StartTimeout = 60 StopTimeout = 60 )
It's possible to override some defaults, by setting the following environment variables: * USE_EXISTING_CLUSTER (boolean): if set to true, envtest will use an existing cluster * TEST_ASSET_KUBE_APISERVER (string): path to the api-server binary to use * TEST_ASSET_ETCD (string): path to the etcd binary to use * TEST_ASSET_KUBECTL (string): path to the kubectl binary to use * KUBEBUILDER_ASSETS (string): directory containing the binaries to use (api-server, etcd and kubectl). Defaults to /usr/local/kubebuilder/bin. * KUBEBUILDER_CONTROLPLANE_START_TIMEOUT (string supported by time.ParseDuration): timeout for test control plane to start. Defaults to 20s. * KUBEBUILDER_CONTROLPLANE_STOP_TIMEOUT (string supported by time.ParseDuration): timeout for test control plane to start. Defaults to 20s. * KUBEBUILDER_ATTACH_CONTROL_PLANE_OUTPUT (boolean): if set to true, the control plane's stdout and stderr are attached to os.Stdout and os.Stderr
Variables ¶
var DefaultKubeAPIServerFlags = controlplane.APIServerDefaultArgs //nolint:staticcheck
DefaultKubeAPIServerFlags exposes the default args for the APIServer so that you can use those to append your own additional arguments.
Deprecated: use APIServer.Configure() instead.
var ( // EmptyArguments constructs a new set of flags with nothing set. // // This is mostly useful for testing helper methods -- you'll want to call // Configure on the APIServer (or etcd) to configure their arguments. EmptyArguments = process.EmptyArguments )
Functions ¶
func CreateCRDs ¶
func CreateCRDs(config *rest.Config, crds []*apiextensionsv1.CustomResourceDefinition) error
CreateCRDs creates the CRDs.
func InstallCRDs ¶
func InstallCRDs(config *rest.Config, options CRDInstallOptions) ([]*apiextensionsv1.CustomResourceDefinition, error)
InstallCRDs installs a collection of CRDs into a cluster by reading the crd yaml files from a directory.
func UninstallCRDs ¶ added in v0.5.0
func UninstallCRDs(config *rest.Config, options CRDInstallOptions) error
UninstallCRDs uninstalls a collection of CRDs by reading the crd yaml files from a directory.
func WaitForCRDs ¶
func WaitForCRDs(config *rest.Config, crds []*apiextensionsv1.CustomResourceDefinition, options CRDInstallOptions) error
WaitForCRDs waits for the CRDs to appear in discovery.
func WaitForWebhooks ¶ added in v0.5.1
func WaitForWebhooks(config *rest.Config, mutatingWebhooks []*admissionv1.MutatingWebhookConfiguration, validatingWebhooks []*admissionv1.ValidatingWebhookConfiguration, options WebhookInstallOptions) error
WaitForWebhooks waits for the Webhooks to be available through API server.
Types ¶
type APIServer ¶ added in v0.5.7
type APIServer = controlplane.APIServer
APIServer is the re-exported APIServer from the internal testing package.
type AuthenticatedUser ¶ added in v0.9.0
type AuthenticatedUser = controlplane.AuthenticatedUser
AuthenticatedUser represets a Kubernetes user that's been provisioned.
type Authn ¶ added in v0.9.0
type Authn = controlplane.Authn
Authn is an authentication method that can be used with the control plane to provision users.
type CRDInstallOptions ¶
type CRDInstallOptions struct {
// Scheme is used to determine if conversion webhooks should be enabled
// for a particular CRD / object.
//
// Conversion webhooks are going to be enabled if an object in the scheme
// implements Hub and Spoke conversions.
//
// If nil, scheme.Scheme is used.
Scheme *runtime.Scheme
// Paths is a list of paths to the directories or files containing CRDs
Paths []string
// CRDs is a list of CRDs to install
CRDs []*apiextensionsv1.CustomResourceDefinition
// ErrorIfPathMissing will cause an error if a Path does not exist
ErrorIfPathMissing bool
// MaxTime is the max time to wait
MaxTime time.Duration
// PollInterval is the interval to check
PollInterval time.Duration
// CleanUpAfterUse will cause the CRDs listed for installation to be
// uninstalled when terminating the test environment.
// Defaults to false.
CleanUpAfterUse bool
// WebhookOptions contains the conversion webhook information to install
// on the CRDs. This field is usually inherited by the EnvTest options.
//
// If you're passing this field manually, you need to make sure that
// the CA information and host port is filled in properly.
WebhookOptions WebhookInstallOptions
}
CRDInstallOptions are the options for installing CRDs.
type ControlPlane ¶ added in v0.5.7
type ControlPlane = controlplane.ControlPlane
ControlPlane is the re-exported ControlPlane type from the internal testing package.
type Environment ¶
type Environment struct {
// ControlPlane is the ControlPlane including the apiserver and etcd
ControlPlane controlplane.ControlPlane
// Scheme is used to determine if conversion webhooks should be enabled
// for a particular CRD / object.
//
// Conversion webhooks are going to be enabled if an object in the scheme
// implements Hub and Spoke conversions.
//
// If nil, scheme.Scheme is used.
Scheme *runtime.Scheme
// Config can be used to talk to the apiserver. It's automatically
// populated if not set using the standard controller-runtime config
// loading.
Config *rest.Config
// CRDInstallOptions are the options for installing CRDs.
CRDInstallOptions CRDInstallOptions
// WebhookInstallOptions are the options for installing webhooks.
WebhookInstallOptions WebhookInstallOptions
// ErrorIfCRDPathMissing provides an interface for the underlying
// CRDInstallOptions.ErrorIfPathMissing. It prevents silent failures
// for missing CRD paths.
ErrorIfCRDPathMissing bool
// CRDs is a list of CRDs to install.
// If both this field and CRDs field in CRDInstallOptions are specified, the
// values are merged.
CRDs []*apiextensionsv1.CustomResourceDefinition
// CRDDirectoryPaths is a list of paths containing CRD yaml or json configs.
// If both this field and Paths field in CRDInstallOptions are specified, the
// values are merged.
CRDDirectoryPaths []string
// BinaryAssetsDirectory is the path where the binaries required for the envtest are
// located in the local environment. This field can be overridden by setting KUBEBUILDER_ASSETS.
BinaryAssetsDirectory string
// UseExistingCluster indicates that this environments should use an
// existing kubeconfig, instead of trying to stand up a new control plane.
// This is useful in cases that need aggregated API servers and the like.
UseExistingCluster *bool
// ControlPlaneStartTimeout is the maximum duration each controlplane component
// may take to start. It defaults to the KUBEBUILDER_CONTROLPLANE_START_TIMEOUT
// environment variable or 20 seconds if unspecified
ControlPlaneStartTimeout time.Duration
// ControlPlaneStopTimeout is the maximum duration each controlplane component
// may take to stop. It defaults to the KUBEBUILDER_CONTROLPLANE_STOP_TIMEOUT
// environment variable or 20 seconds if unspecified
ControlPlaneStopTimeout time.Duration
// KubeAPIServerFlags is the set of flags passed while starting the api server.
//
// Deprecated: use ControlPlane.GetAPIServer().Configure() instead.
KubeAPIServerFlags []string
// AttachControlPlaneOutput indicates if control plane output will be attached to os.Stdout and os.Stderr.
// Enable this to get more visibility of the testing control plane.
// It respect KUBEBUILDER_ATTACH_CONTROL_PLANE_OUTPUT environment variable.
AttachControlPlaneOutput bool
}
Environment creates a Kubernetes test environment that will start / stop the Kubernetes control plane and install extension APIs.
func (*Environment) AddUser ¶ added in v0.9.0
func (te *Environment) AddUser(user User, baseConfig *rest.Config) (*AuthenticatedUser, error)
AddUser provisions a new user for connecting to this Environment. The user will have the specified name & belong to the specified groups.
If you specify a "base" config, the returned REST Config will contain those settings as well as any required by the authentication method. You can use this to easily specify options like QPS.
This is effectively a convinience alias for ControlPlane.AddUser -- see that for more low-level details.
func (*Environment) Start ¶
func (te *Environment) Start() (*rest.Config, error)
Start starts a local Kubernetes server and updates te.ApiserverPort with the port it is listening on.
func (*Environment) Stop ¶
func (te *Environment) Stop() error
Stop stops a running server. Previously installed CRDs, as listed in CRDInstallOptions.CRDs, will be uninstalled if CRDInstallOptions.CleanUpAfterUse are set to true.
type Etcd ¶ added in v0.5.7
type Etcd = controlplane.Etcd
Etcd is the re-exported Etcd from the internal testing package.
type ListenAddr ¶ added in v0.9.0
type ListenAddr = process.ListenAddr
ListenAddr indicates the address and port that the API server should listen on.
type SecureServing ¶ added in v0.9.0
type SecureServing = controlplane.SecureServing
SecureServing contains details describing how the API server should serve its secure endpoint.
type User ¶ added in v0.9.0
type User = controlplane.User
User represents a Kubernetes user to provision for auth purposes.
type WebhookInstallOptions ¶ added in v0.5.1
type WebhookInstallOptions struct {
// Paths is a list of paths to the directories or files containing the mutating or validating webhooks yaml or json configs.
Paths []string
// MutatingWebhooks is a list of MutatingWebhookConfigurations to install
MutatingWebhooks []*admissionv1.MutatingWebhookConfiguration
// ValidatingWebhooks is a list of ValidatingWebhookConfigurations to install
ValidatingWebhooks []*admissionv1.ValidatingWebhookConfiguration
// IgnoreErrorIfPathMissing will ignore an error if a DirectoryPath does not exist when set to true
IgnoreErrorIfPathMissing bool
// LocalServingHost is the host for serving webhooks on.
// it will be automatically populated
LocalServingHost string
// LocalServingPort is the allocated port for serving webhooks on.
// it will be automatically populated by a random available local port
LocalServingPort int
// LocalServingCertDir is the allocated directory for serving certificates.
// it will be automatically populated by the local temp dir
LocalServingCertDir string
// CAData is the CA that can be used to trust the serving certificates in LocalServingCertDir.
LocalServingCAData []byte
// LocalServingHostExternalName is the hostname to use to reach the webhook server.
LocalServingHostExternalName string
// MaxTime is the max time to wait
MaxTime time.Duration
// PollInterval is the interval to check
PollInterval time.Duration
}
WebhookInstallOptions are the options for installing mutating or validating webhooks.
func (*WebhookInstallOptions) Cleanup ¶ added in v0.5.1
func (o *WebhookInstallOptions) Cleanup() error
Cleanup cleans up cert directories.
func (*WebhookInstallOptions) Install ¶ added in v0.5.1
func (o *WebhookInstallOptions) Install(config *rest.Config) error
Install installs specified webhooks to the API server.
func (*WebhookInstallOptions) ModifyWebhookDefinitions ¶ added in v0.5.1
func (o *WebhookInstallOptions) ModifyWebhookDefinitions() error
ModifyWebhookDefinitions modifies webhook definitions by: - applying CABundle based on the provided tinyca - if webhook client config uses service spec, it's removed and replaced with direct url.
func (*WebhookInstallOptions) PrepWithoutInstalling ¶ added in v0.6.4
func (o *WebhookInstallOptions) PrepWithoutInstalling() error
PrepWithoutInstalling does the setup parts of Install (populating host-port, setting up CAs, etc), without actually truing to do anything with webhook definitions. This is largely useful for internal testing of controller-runtime, where we need a random host-port & caData for webhook tests, but may be useful in similar scenarios.