featuregate

Documentation

Index

• Constants
• func NewComponentGlobalsRegistry() *componentGlobalsRegistry
• func NewFeatureGate() *featureGate
• func NewVersionedFeatureGate(emulationVersion *version.Version) *featureGate
• type ComponentGlobals
• type ComponentGlobalsRegistry
• type Feature
• type FeatureGate
• type FeatureSpec
• type MutableFeatureGate
• type MutableVersionedFeatureGate
• type PromotionVersionMapping
• type VersionMapping
• type VersionedSpecs
  • func (g VersionedSpecs) Len() int
  • func (g VersionedSpecs) Less(i, j int) bool
  • func (g VersionedSpecs) Swap(i, j int)

Constants

const (
	PreAlpha = prerelease("PRE-ALPHA")
	// Values for PreRelease.
	Alpha = prerelease("ALPHA")
	Beta  = prerelease("BETA")
	GA    = prerelease("")

	// Deprecated
	Deprecated = prerelease("DEPRECATED")
)

const (
	DefaultKubeComponent = "kube"
)

Functions

func NewComponentGlobalsRegistry

func NewComponentGlobalsRegistry() *componentGlobalsRegistry

func NewFeatureGate

func NewFeatureGate() *featureGate

NewFeatureGate creates a feature gate with the current binary version.

func NewVersionedFeatureGate

func NewVersionedFeatureGate(emulationVersion *version.Version) *featureGate

NewVersionedFeatureGate creates a feature gate with the emulation version set to the provided version. SetEmulationVersion can be called after to change emulation version to a desired value.

Types

type ComponentGlobals

type ComponentGlobals struct {
	// contains filtered or unexported fields
}

ComponentGlobals stores the global variables for a component for easy access.

type ComponentGlobalsRegistry

type ComponentGlobalsRegistry interface {
	// EffectiveVersionFor returns the EffectiveVersion registered under the component.
	// Returns nil if the component is not registered.
	EffectiveVersionFor(component string) baseversion.EffectiveVersion
	// FeatureGateFor returns the FeatureGate registered under the component.
	// Returns nil if the component is not registered.
	FeatureGateFor(component string) FeatureGate
	// Register registers the EffectiveVersion and FeatureGate for a component.
	// returns error if the component is already registered.
	Register(component string, effectiveVersion baseversion.MutableEffectiveVersion, featureGate MutableVersionedFeatureGate) error
	// ComponentGlobalsOrRegister would return the registered global variables for the component if it already exists in the registry.
	// Otherwise, the provided variables would be registered under the component, and the same variables would be returned.
	ComponentGlobalsOrRegister(component string, effectiveVersion baseversion.MutableEffectiveVersion, featureGate MutableVersionedFeatureGate) (baseversion.MutableEffectiveVersion, MutableVersionedFeatureGate)
	// AddFlags adds flags of "--emulated-version" and "--feature-gates"
	AddFlags(fs *pflag.FlagSet)
	// Set sets the flags for all global variables for all components registered.
	Set() error
	// SetFallback calls Set() if it has never been called.
	SetFallback() error
	// Validate calls the Validate() function for all the global variables for all components registered.
	Validate() []error
	// Reset removes all stored ComponentGlobals, configurations, and version mappings.
	Reset()
	// SetEmulationVersionMapping sets the mapping from the emulation version of one component
	// to the emulation version of another component.
	// Once set, the emulation version of the toComponent will be determined by the emulation version of the fromComponent,
	// and cannot be set from cmd flags anymore.
	// For a given component, its emulation version can only depend on one other component, no multiple dependency is allowed.
	SetEmulationVersionMapping(fromComponent, toComponent string, f VersionMapping) error
}

var DefaultComponentGlobalsRegistry ComponentGlobalsRegistry = NewComponentGlobalsRegistry()

DefaultComponentGlobalsRegistry is the global var to store the effective versions and feature gates for all components for easy access. Example usage: // register the component effective version and feature gate first _, _ = utilversion.DefaultComponentGlobalsRegistry.ComponentGlobalsOrRegister(utilversion.DefaultKubeComponent, utilversion.DefaultKubeEffectiveVersion(), utilfeature.DefaultMutableFeatureGate) wardleEffectiveVersion := utilversion.NewEffectiveVersion("1.2") wardleFeatureGate := featuregate.NewFeatureGate() utilruntime.Must(utilversion.DefaultComponentGlobalsRegistry.Register(apiserver.WardleComponentName, wardleEffectiveVersion, wardleFeatureGate, false))

cmd := &cobra.Command{
 ...
	// call DefaultComponentGlobalsRegistry.Set() in PersistentPreRunE
	PersistentPreRunE: func(*cobra.Command, []string) error {
		if err := utilversion.DefaultComponentGlobalsRegistry.Set(); err != nil {
			return err
		}
 ...
	},
	RunE: func(c *cobra.Command, args []string) error {
		// call utilversion.DefaultComponentGlobalsRegistry.Validate() somewhere
	},
}

flags := cmd.Flags() // add flags utilversion.DefaultComponentGlobalsRegistry.AddFlags(flags)

type Feature

type Feature string

type FeatureGate

type FeatureGate interface {
	// Enabled returns true if the key is enabled.
	Enabled(key Feature) bool
	// KnownFeatures returns a slice of strings describing the FeatureGate's known features.
	KnownFeatures() []string
	// DeepCopy returns a deep copy of the FeatureGate object, such that gates can be
	// set on the copy without mutating the original. This is useful for validating
	// config against potential feature gate changes before committing those changes.
	DeepCopy() MutableVersionedFeatureGate
	// Validate checks if the flag gates are valid at the emulated version.
	Validate() []error
}

FeatureGate indicates whether a given feature is enabled or not

type FeatureSpec

type FeatureSpec struct {
	// Default is the default enablement state for the feature
	Default bool
	// LockToDefault indicates that the feature is locked to its default and cannot be changed
	LockToDefault bool
	// PreRelease indicates the current maturity level of the feature
	PreRelease prerelease
	// Version indicates the earliest version from which this FeatureSpec is valid.
	// If multiple FeatureSpecs exist for a Feature, the one with the highest version that is less
	// than or equal to the effective version of the component is used.
	Version *version.Version
}

type MutableFeatureGate

type MutableFeatureGate interface {
	FeatureGate

	// AddFlag adds a flag for setting global feature gates to the specified FlagSet.
	AddFlag(fs *pflag.FlagSet)
	// Close sets closed to true, and prevents subsequent calls to Add
	Close()
	// Set parses and stores flag gates for known features
	// from a string like feature1=true,feature2=false,...
	Set(value string) error
	// SetFromMap stores flag gates for known features from a map[string]bool or returns an error
	SetFromMap(m map[string]bool) error
	// Add adds features to the featureGate.
	Add(features map[Feature]FeatureSpec) error
	// GetAll returns a copy of the map of known feature names to feature specs.
	GetAll() map[Feature]FeatureSpec
	// AddMetrics adds feature enablement metrics
	AddMetrics()
	// OverrideDefault sets a local override for the registered default value of a named
	// feature. If the feature has not been previously registered (e.g. by a call to Add), has a
	// locked default, or if the gate has already registered itself with a FlagSet, a non-nil
	// error is returned.
	//
	// When two or more components consume a common feature, one component can override its
	// default at runtime in order to adopt new defaults before or after the other
	// components. For example, a new feature can be evaluated with a limited blast radius by
	// overriding its default to true for a limited number of components without simultaneously
	// changing its default for all consuming components.
	OverrideDefault(name Feature, override bool) error
}

MutableFeatureGate parses and stores flag gates for known features from a string like feature1=true,feature2=false,...

type MutableVersionedFeatureGate

type MutableVersionedFeatureGate interface {
	MutableFeatureGate
	// EmulationVersion returns the version the feature gate is set to emulate.
	// If set, the feature gate would enable/disable features based on
	// feature availability and pre-release at the emulated version instead of the binary version.
	EmulationVersion() *version.Version
	// SetEmulationVersion overrides the emulationVersion of the feature gate.
	// Otherwise, the emulationVersion will be the same as the binary version.
	// If set, the feature defaults and availability will be as if the binary is at the emulated version.
	SetEmulationVersion(emulationVersion *version.Version) error
	// GetAll returns a copy of the map of known feature names to versioned feature specs.
	GetAllVersioned() map[Feature]VersionedSpecs
	// AddVersioned adds versioned feature specs to the featureGate.
	AddVersioned(features map[Feature]VersionedSpecs) error
	// OverrideDefaultAtVersion sets a local override for the registered default value of a named
	// feature for the prerelease lifecycle the given version is at.
	// If the feature has not been previously registered (e.g. by a call to Add),
	// has a locked default, or if the gate has already registered itself with a FlagSet, a non-nil
	// error is returned.
	//
	// When two or more components consume a common feature, one component can override its
	// default at runtime in order to adopt new defaults before or after the other
	// components. For example, a new feature can be evaluated with a limited blast radius by
	// overriding its default to true for a limited number of components without simultaneously
	// changing its default for all consuming components.
	OverrideDefaultAtVersion(name Feature, override bool, ver *version.Version) error
	// ExplicitlySet returns true if the feature value is explicitly set instead of
	// being derived from the default values or special features.
	ExplicitlySet(name Feature) bool
	// ResetFeatureValueToDefault resets the value of the feature back to the default value.
	ResetFeatureValueToDefault(name Feature) error
	// DeepCopyAndReset copies all the registered features of the FeatureGate object, with all the known features and overrides,
	// and resets all the enabled status of the new feature gate.
	// This is useful for creating a new instance of feature gate without inheriting all the enabled configurations of the base feature gate.
	DeepCopyAndReset() MutableVersionedFeatureGate
}

MutableVersionedFeatureGate parses and stores flag gates for known features from a string like feature1=true,feature2=false,... MutableVersionedFeatureGate sets options based on the emulated version of the featured gate.

type PromotionVersionMapping

type PromotionVersionMapping map[prerelease]string

type VersionMapping

type VersionMapping func(from *version.Version) *version.Version

type VersionedSpecs

type VersionedSpecs []FeatureSpec

func (VersionedSpecs) Len

func (g VersionedSpecs) Len() int

func (VersionedSpecs) Less

func (g VersionedSpecs) Less(i, j int) bool

func (VersionedSpecs) Swap

func (g VersionedSpecs) Swap(i, j int)