util

README

Feature Gates

Feature gates allow users to enable or disable certain features by setting the "PGO_FEATURE_GATES" environment variable to a list similar to "feature1=true,feature2=false,..." in the PGO Deployment.

This capability leverages the relevant Kubernetes packages. Documentation and code implementation examples are given below.

• Documentation:

  • https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/

• Package Information:

  • https://pkg.go.dev/k8s.io/component-base@v0.20.1/featuregate

• Adding the feature gate key:

  • https://releases.k8s.io/v1.20.0/pkg/features/kube_features.go#L27

• Adding the feature gate to the known features map:

  • https://releases.k8s.io/v1.20.0/pkg/features/kube_features.go#L729-732

• Adding features to the featureGate

  • https://releases.k8s.io/v1.20.0/staging/src/k8s.io/component-base/featuregate/feature_gate.go#L110-L111

• Setting the feature gates

  • https://releases.k8s.io/v1.20.0/staging/src/k8s.io/component-base/featuregate/feature_gate.go#L105-L107

Developing with Feature Gates in PGO

To add a new feature gate, a few steps are required. First, in internal/util/features.go, you will add a feature gate key name. As an example, for a new feature called 'FeatureName', you would add a new constant and comment describing what the feature gate controls at the top of the file, similar to

// Enables FeatureName in PGO
FeatureName featuregate.Feature = "FeatureName"

Next, add a new entry to the pgoFeatures map

var pgoFeatures = map[featuregate.Feature]featuregate.FeatureSpec{
    FeatureName: {Default: false, PreRelease: featuregate.Alpha},
}

where FeatureName is the constant defined previously, Default: false sets the default behavior and PreRelease: featuregate.Alpha. The possible PreRelease values are Alpha, Beta, GA and Deprecated.

• https://pkg.go.dev/k8s.io/component-base@v0.20.1/featuregate#pkg-constants

By Kubernetes convention, Alpha features have almost always been disabled by default. Beta features are generally enabled by default.

• https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/#feature-stages

Prior to Kubernetes 1.24, both Beta features and APIs were enabled by default. Starting in v1.24, new Beta APIs are generally disabled by default, while Beta features remain enabled by default.

• https://kubernetes.io/blog/2021/07/14/upcoming-changes-in-kubernetes-1-22/#kubernetes-api-removals
• https://kubernetes.io/blog/2022/05/03/kubernetes-1-24-release-announcement/#beta-apis-off-by-default
• https://github.com/kubernetes/enhancements/tree/master/keps/sig-architecture/3136-beta-apis-off-by-default#goals

For consistency with Kubernetes, we recommend that feature-gated features be configured as Alpha and disabled by default. Any Beta features added should stay consistent with Kubernetes practice and be enabled by default, but we should keep an eye out for changes to these standards and adjust as needed.

Once the above items are set, you can then use your feature gated value in the code base to control feature behavior using something like

if util.DefaultMutableFeatureGate.Enabled(util.FeatureName)

To test the feature gate, set the PGO_FEATURE_GATES environment variable to enable the new feature as follows

PGO_FEATURE_GATES="FeatureName=true"

Note that for more than one feature, this variable accepts a comma delimited list, e.g.

PGO_FEATURE_GATES="FeatureName=true,FeatureName2=true,FeatureName3=true"

While PGO_FEATURE_GATES does not have to be set, please note that the features must be defined before use, otherwise PGO deployment will fail with the following message panic: unable to parse and store configured feature gates. unrecognized feature gate

Also, the features must have boolean values, otherwise you will see panic: unable to parse and store configured feature gates. invalid value

When dealing with tests that do not invoke cmd/postgres-operator/main.go, keep in mind that you will need to ensure that you invoke the AddAndSetFeatureGates function. Otherwise, any test that references the undefined feature gate will fail with a panic message similar to "feature "FeatureName" is not registered in FeatureGate"

To correct for this, you simply need a line similar to

err := util.AddAndSetFeatureGates("")

Documentation

Index

• Constants
• Variables
• func AddAndSetFeatureGates(features string) error
• func GenerateASCIIPassword(length int) (string, error)
• func GenerateAlphaNumericPassword(length int) (string, error)
• func SQLQuoteIdentifier(identifier string) string
• func SQLQuoteLiteral(literal string) string

Constants

const (
	// Every feature gate should add a key here following this template:
	//
	// // Enables FeatureName...
	// FeatureName featuregate.Feature = "FeatureName"
	//
	// - https://releases.k8s.io/v1.20.0/pkg/features/kube_features.go#L27
	//
	// Feature gates should be listed in alphabetical, case-sensitive
	// (upper before any lower case character) order.
	//
	// Enables support of custom sidecars for PostgreSQL instance Pods
	InstanceSidecars featuregate.Feature = "InstanceSidecars"
	//
	// Enables support of custom sidecars for pgBouncer Pods
	PGBouncerSidecars featuregate.Feature = "PGBouncerSidecars"
)

const (
	// DefaultGeneratedPasswordLength is the default length of what a generated
	// password should be if it's not set elsewhere
	DefaultGeneratedPasswordLength = 24
)

The following constant is used as a part of password generation.

Variables

var DefaultMutableFeatureGate featuregate.MutableFeatureGate = featuregate.NewFeatureGate()

DefaultMutableFeatureGate is a mutable, shared global FeatureGate. It is used to indicate whether a given feature is enabled or not.

- https://pkg.go.dev/k8s.io/apiserver/pkg/util/feature - https://releases.k8s.io/v1.20.0/staging/src/k8s.io/apiserver/pkg/util/feature/feature_gate.go#L24-L28

Functions

func AddAndSetFeatureGates

func AddAndSetFeatureGates(features string) error

AddAndSetFeatureGates utilizes the Kubernetes feature gate packages to first add the default PGO features to the featureGate and then set the values provided via the 'PGO_FEATURE_GATES' environment variable. This function expects a string like feature1=true,feature2=false,...

- https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/ - https://pkg.go.dev/k8s.io/component-base@v0.20.1/featuregate

func GenerateASCIIPassword

func GenerateASCIIPassword(length int) (string, error)

GenerateASCIIPassword returns a random string of printable ASCII characters.

func GenerateAlphaNumericPassword

func GenerateAlphaNumericPassword(length int) (string, error)

GenerateAlphaNumericPassword returns a random alphanumeric string.

func SQLQuoteIdentifier

func SQLQuoteIdentifier(identifier string) string

SQLQuoteIdentifier quotes an "identifier" (e.g. a table or a column name) to be used as part of an SQL statement.

Any double quotes in name will be escaped. The quoted identifier will be case sensitive when used in a query. If the input string contains a zero byte, the result will be truncated immediately before it.

Implementation borrowed from lib/pq: https://github.com/lib/pq which is licensed under the MIT License

func SQLQuoteLiteral

func SQLQuoteLiteral(literal string) string

SQLQuoteLiteral quotes a 'literal' (e.g. a parameter, often used to pass literal to DDL and other statements that do not accept parameters) to be used as part of an SQL statement.

Any single quotes in name will be escaped. Any backslashes (i.e. "\") will be replaced by two backslashes (i.e. "\\") and the C-style escape identifier that PostgreSQL provides ('E') will be prepended to the string.

Implementation borrowed from lib/pq: https://github.com/lib/pq which is licensed under the MIT License. Curiously, @jkatz and @cbandy were the ones who worked on the patch to add this, prior to being at Crunchy Data