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

    View Source
    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

      View Source
      var DefaultKubeAPIServerFlags = integration.APIServerDefaultArgs

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

        Functions

        func CreateCRDs

        func CreateCRDs(config *rest.Config, crds []client.Object) error

          CreateCRDs creates the CRDs

          func InstallCRDs

          func InstallCRDs(config *rest.Config, options CRDInstallOptions) ([]client.Object, error)

            InstallCRDs installs a collection of CRDs into a cluster by reading the crd yaml files from a directory

            func UninstallCRDs

            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 []client.Object, options CRDInstallOptions) error

                WaitForCRDs waits for the CRDs to appear in discovery

                func WaitForWebhooks

                func WaitForWebhooks(config *rest.Config,
                	mutatingWebhooks []client.Object,
                	validatingWebhooks []client.Object,
                	options WebhookInstallOptions) error

                  WaitForWebhooks waits for the Webhooks to be available through API server

                  Types

                  type APIServer

                  type APIServer = integration.APIServer

                    APIServer is the re-exported APIServer type from the internal integration package

                    type CRDInstallOptions

                    type CRDInstallOptions struct {
                    	// Paths is a list of paths to the directories or files containing CRDs
                    	Paths []string
                    
                    	// CRDs is a list of CRDs to install
                    	CRDs []client.Object
                    
                    	// 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
                    }

                      CRDInstallOptions are the options for installing CRDs

                      type ControlPlane

                      type ControlPlane = integration.ControlPlane

                        ControlPlane is the re-exported ControlPlane type from the internal integration package

                        type Environment

                        type Environment struct {
                        	// ControlPlane is the ControlPlane including the apiserver and etcd
                        	ControlPlane integration.ControlPlane
                        
                        	// 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 []client.Object
                        
                        	// 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
                        
                        	// UseExisting 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.
                        	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) 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

                              type Etcd = integration.Etcd

                                Etcd is the re-exported Etcd type from the internal integration package

                                type WebhookInstallOptions

                                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 []client.Object
                                
                                	// ValidatingWebhooks is a list of ValidatingWebhookConfigurations to install
                                	ValidatingWebhooks []client.Object
                                
                                	// 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

                                  func (o *WebhookInstallOptions) Cleanup() error

                                    Cleanup cleans up cert directories

                                    func (*WebhookInstallOptions) Install

                                    func (o *WebhookInstallOptions) Install(config *rest.Config) error

                                      Install installs specified webhooks to the API server

                                      func (*WebhookInstallOptions) ModifyWebhookDefinitions

                                      func (o *WebhookInstallOptions) ModifyWebhookDefinitions(caData []byte) 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

                                        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.

                                          Directories

                                          Path Synopsis
                                          Package printer contains setup for a friendlier Ginkgo printer that's easier to parse by test automation.
                                          Package printer contains setup for a friendlier Ginkgo printer that's easier to parse by test automation.