cnpg

package
v0.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 15, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// CNPG Kubernetes API constants
	CNPGAPIGroup     = "postgresql.cnpg.io"
	CNPGAPIVersion   = "v1"
	CNPGResourceName = "clusters"

	// CNPG label for cluster identification
	CNPGClusterLabel = "cnpg.io/cluster"

	// CNPG parameters path in the Cluster CRD spec
	CNPGParametersPath = "spec.postgresql.parameters"

	// Configuration application limits
	ConfigApplyMaxRetries = 5
	ConfigApplyRetryDelay = 5 * time.Second

	// Rolling restart wait times - increased for production scenarios where
	// replicas may take longer to catch up with WAL during heavy workloads
	MaxWaitTimeClusterHealthy  = 60 * time.Minute
	PollIntervalClusterHealthy = 5 * time.Second
)
View Source 
const DEFAULT_CONFIG_KEY = "cnpg"
View Source 
const DEFAULT_CONTAINER_NAME = "postgres"
View Source 
const (
	// MinTimeSinceFailover is the minimum time to wait after detecting a failover
	// before checking cluster health. This prevents rapid successive checks
	// immediately after failover detection.
	MinTimeSinceFailover = 30 * time.Second
)

Variables

View Source 
var CNPGManagedParameters = map[string]bool{

	"archive_mode":              true,
	"archive_command":           true,
	"archive_cleanup_command":   true,
	"restore_command":           true,
	"recovery_end_command":      true,
	"recovery_target":           true,
	"recovery_target_action":    true,
	"recovery_target_inclusive": true,
	"recovery_target_lsn":       true,
	"recovery_target_name":      true,
	"recovery_target_time":      true,
	"recovery_target_timeline":  true,
	"recovery_target_xid":       true,

	"hot_standby":               true,
	"primary_conninfo":          true,
	"primary_slot_name":         true,
	"recovery_min_apply_delay":  true,
	"synchronous_standby_names": true,

	"listen_addresses":        true,
	"port":                    true,
	"unix_socket_directories": true,
	"unix_socket_group":       true,
	"unix_socket_permissions": true,

	"ssl":                                    true,
	"ssl_ca_file":                            true,
	"ssl_cert_file":                          true,
	"ssl_crl_file":                           true,
	"ssl_dh_params_file":                     true,
	"ssl_ecdh_curve":                         true,
	"ssl_key_file":                           true,
	"ssl_passphrase_command":                 true,
	"ssl_passphrase_command_supports_reload": true,
	"ssl_prefer_server_ciphers":              true,

	"log_destination":          true,
	"log_directory":            true,
	"log_file_mode":            true,
	"log_filename":             true,
	"log_rotation_age":         true,
	"log_rotation_size":        true,
	"log_truncate_on_rotation": true,
	"logging_collector":        true,
	"stats_temp_directory":     true,

	"syslog_facility":         true,
	"syslog_ident":            true,
	"syslog_sequence_numbers": true,
	"syslog_split_messages":   true,

	"cluster_name":         true,
	"config_file":          true,
	"data_directory":       true,
	"hba_file":             true,
	"ident_file":           true,
	"external_pid_file":    true,
	"promote_trigger_file": true,

	"restart_after_crash":     true,
	"allow_alter_system":      true,
	"allow_system_table_mods": true,
	"data_sync_retry":         true,
	"jit_provider":            true,

	"shared_preload_libraries": true,

	"event_source": true,

	"bonjour":      true,
	"bonjour_name": true,
}

CNPGManagedParameters are parameters that CNPG's webhook validation explicitly prevents from being modified, or that CNPG manages internally and should not be overridden by tuning configurations.

We MUST filter them out to prevent breaking the cluster.

Example: shared_preload_libraries="" would remove pg_stat_statements and break metrics!

Source: https://cloudnative-pg.io/documentation/current/postgresql_conf/

Functions

func Collectors 

func Collectors(pool *pgxpool.Pool, kubeClient kubernetes.Client, clusterName string, containerName string, PGVersion string, logger *log.Logger) []agent.MetricCollector

func ConvertToCNPGFormat 

func ConvertToCNPGFormat(name string, value string, knobConfig *agent.PGConfigRow) string

ConvertToCNPGFormat converts PostgreSQL parameter values to CNPG human-readable format. CNPG expects memory values like "2GB", "256MB" instead of raw block counts like "262144".

For non-memory parameters, returns the original value unchanged.

func ConvertWithUnit 

func ConvertWithUnit(value, unit string) string

ConvertWithUnit converts a value with a given unit to CNPG format. Example: value="262144", unit="8kB" → "2GB"

func DetectConfigFromConfigFile 

func DetectConfigFromConfigFile() bool

func DetectConfigFromEnv 

func DetectConfigFromEnv() bool

func IsCNPGManagedParameter 

func IsCNPGManagedParameter(name string) bool

IsCNPGManagedParameter returns true if the parameter is managed by CNPG and should not be modified by the tuning agent.

Types

type CNPGAdapter 

type CNPGAdapter struct {
	agent.CommonAgent
	GuardrailSettings guardrails.Config
	Config            Config
	PGDriver          *pgxpool.Pool
	PGVersion         string
	K8sClient         kubernetes.Client
	State             *State
}

func CreateCNPGAdapter 

func CreateCNPGAdapter() (*CNPGAdapter, error)

func (*CNPGAdapter) ApplyConfig 

func (adapter *CNPGAdapter) ApplyConfig(proposedConfig *agent.ProposedConfigResponse) error

func (*CNPGAdapter) CheckForFailover 

func (adapter *CNPGAdapter) CheckForFailover(ctx context.Context) error

CheckForFailover checks if a failover has occurred since last check. Returns FailoverDetectedError if primary changed, nil otherwise.

func (*CNPGAdapter) CheckRestartRequired 

func (adapter *CNPGAdapter) CheckRestartRequired(ctx context.Context, changedParams map[string]string) (bool, []string, error)

CheckRestartRequired checks if any of the changed parameters require database restart. Returns:

  • bool: true if any parameter requires restart
  • []string: list of parameter names that require restart
  • error: any error encountered

func (*CNPGAdapter) GetActiveConfig 

func (adapter *CNPGAdapter) GetActiveConfig() (agent.ConfigArraySchema, error)

func (*CNPGAdapter) GetCurrentConfig 

func (adapter *CNPGAdapter) GetCurrentConfig(ctx context.Context) (map[string]string, error)

GetCurrentConfig retrieves the current PostgreSQL configuration values. Returns a map of parameter name to current value in CNPG format (e.g., "2GB"). This is used to compare against proposed config to avoid applying unchanged parameters.

func (*CNPGAdapter) GetMetrics 

func (adapter *CNPGAdapter) GetMetrics() ([]metrics.FlatValue, error)

GetMetrics overrides CommonAgent.GetMetrics to check for failover before collecting metrics

func (*CNPGAdapter) GetSystemInfo 

func (adapter *CNPGAdapter) GetSystemInfo() ([]metrics.FlatValue, error)

func (*CNPGAdapter) Guardrails 

func (adapter *CNPGAdapter) Guardrails() *guardrails.Signal

func (*CNPGAdapter) HandleFailoverDetected 

func (adapter *CNPGAdapter) HandleFailoverDetected(ctx context.Context, failoverErr *FailoverDetectedError) error

HandleFailoverDetected is called when a failover is detected. It sends an error to the backend and updates tracking to the new primary.

type Config 

type Config struct {
	Namespace      string `mapstructure:"namespace" validate:"required"`
	KubeconfigPath string `mapstructure:"kubeconfig_path"`
	ClusterName    string `mapstructure:"cluster_name" validate:"required"` // Required: CNPG cluster name for dynamic pod discovery
	PodName        string `mapstructure:"pod_name"`                         // Optional: if not specified, auto-discovers primary pod
	ContainerName  string `mapstructure:"container_name"`                   // Optional: defaults to "postgres" if not specified
}

func ConfigFromViper 

func ConfigFromViper() (Config, error)

type FailoverDetectedError 

type FailoverDetectedError struct {
	OldPrimary string
	NewPrimary string
	Message    string
}

FailoverDetectedError is returned when a failover is detected during tuning. This signals that the tuning session should terminate gracefully.

func (*FailoverDetectedError) Error 

func (e *FailoverDetectedError) Error() string

type State 

type State struct {
	LastGuardrailCheck time.Time
	LastAppliedConfig  time.Time

	// Failover detection
	// LastKnownPrimary is the primary pod name from the last check
	// Used to detect when primary changes (failover)
	LastKnownPrimary string
	// LastFailoverTime is when the last failover was detected
	// Used to prevent config applications during failover recovery period
	LastFailoverTime time.Time
	// contains filtered or unexported fields
}

func (*State) CancelOperations 

func (s *State) CancelOperations()

CancelOperations cancels any in-flight operations Call this when failover is detected to abort PostgreSQL queries immediately

func (*State) CreateOperationsContext 

func (s *State) CreateOperationsContext()

CreateOperationsContext creates a new cancellable context for operations Call this when the adapter is initialized and when recovery completes

func (*State) GetLastKnownPrimary 

func (s *State) GetLastKnownPrimary() string

GetLastKnownPrimary safely reads the last known primary pod

func (*State) GetOperationsContext 

func (s *State) GetOperationsContext() context.Context

GetOperationsContext returns the current operations context This context will be cancelled when failover is detected During recovery, returns a pre-cancelled context

func (*State) SetLastFailoverTime 

func (s *State) SetLastFailoverTime(t time.Time)

SetLastFailoverTime safely updates the last failover timestamp

func (*State) SetLastKnownPrimary 

func (s *State) SetLastKnownPrimary(primaryPod string)

SetLastKnownPrimary safely updates the last known primary pod

func (*State) TimeSinceLastFailover 

func (s *State) TimeSinceLastFailover() time.Duration

TimeSinceLastFailover safely returns time since last failover

func (*State) TimeSinceLastGuardrailCheck 

func (s *State) TimeSinceLastGuardrailCheck() time.Duration

TimeSinceLastGuardrailCheck safely returns time since last guardrail check

func (*State) UpdateLastAppliedConfig 

func (s *State) UpdateLastAppliedConfig()

UpdateLastAppliedConfig safely updates the last applied config timestamp

func (*State) UpdateLastGuardrailCheck 

func (s *State) UpdateLastGuardrailCheck()

UpdateLastGuardrailCheck safely updates the last guardrail check timestamp

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.