Documentation
¶
Overview ¶
Package kubernetes provides a Kubernetes client with auto-detection: 1. Try in-cluster config first (for when agent runs as a pod) 2. Fall back to kubeconfig file (configPath or default ~/.kube/config) Also provides light wrappers around Kubernetes resources for simpler usage.
Index ¶
- func CNPGContainerMetricsCollector(client Client, clusterName string, containerName string) func(ctx context.Context, state *agent.MetricsState) error
- func CollectContainerMetrics(ctx context.Context, containerClient ContainerClient, ...) error
- func ContainerMetricsCollector(client Client, podName string, containerName string) func(ctx context.Context, state *agent.MetricsState) error
- func PatchCRDParameters(req CRDPatchRequest) error
- func TriggerCNPGRollingRestart(ctx context.Context, client Client, clusterName string, logger *log.Logger) error
- func WaitForCNPGClusterHealthy(ctx context.Context, client Client, clusterName string, ...) error
- type CNPGClusterStatus
- type CRDPatchRequest
- type Client
- func (c *Client) ContainerClient(podName string, containerName string) ContainerClient
- func (c *Client) FindCNPGPrimaryPod(ctx context.Context, clusterName string) (string, error)
- func (c *Client) GetCNPGClusterStatus(ctx context.Context, clusterName string) (*CNPGClusterStatus, error)
- func (c *Client) PodClient(podName string) PodClient
- type ContainerClient
- func (cc *ContainerClient) CPULimitCoresMilli(ctx context.Context) (int64, error)
- func (cc *ContainerClient) CPUUsageMillicores(ctx context.Context) (int64, error)
- func (cc *ContainerClient) DiskInfo(ctx context.Context) (*DiskInfo, error)
- func (cc *ContainerClient) GetContainerSystemInfo(ctx context.Context) ([]metrics.FlatValue, error)
- func (cc *ContainerClient) IOStats(ctx context.Context) (*ContainerIOStats, error)
- func (cc *ContainerClient) LoadAverage(ctx context.Context) (float64, error)
- func (cc *ContainerClient) MemoryLimitBytes(ctx context.Context) (int64, error)
- func (cc *ContainerClient) MemoryUsageBytes(ctx context.Context) (int64, error)
- func (cc *ContainerClient) NetworkStats(ctx context.Context) (*NetworkStats, error)
- func (cc *ContainerClient) NodeOSInfo(ctx context.Context) (*NodeOSInfo, error)
- type ContainerIOStats
- type ContainerMetricsCache
- type ContainerMetricsConfig
- type DiskInfo
- type NetworkStats
- type NodeOSInfo
- type PodClient
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CNPGContainerMetricsCollector ¶
func CNPGContainerMetricsCollector(client Client, clusterName string, containerName string) func(ctx context.Context, state *agent.MetricsState) error
CNPGContainerMetricsCollector returns a collector function that dynamically discovers the CNPG primary pod before collecting metrics. This ensures metrics are always collected from the current primary, even after failovers.
func CollectContainerMetrics ¶
func CollectContainerMetrics(ctx context.Context, containerClient ContainerClient, state *agent.MetricsState) error
CollectContainerMetrics gathers container metrics from Kubernetes It collects CPU and memory usage, as well as I/O statistics, calculating deltas where appropriate
func ContainerMetricsCollector ¶
func ContainerMetricsCollector(client Client, podName string, containerName string) func(ctx context.Context, state *agent.MetricsState) error
ContainerMetricsCollector returns a collector function that gathers container metrics from Kubernetes
func PatchCRDParameters ¶
func PatchCRDParameters(req CRDPatchRequest) error
PatchCRDParameters applies PostgreSQL configuration parameters to a Kubernetes CRD resource. This is a generic function that can work with different operators (CNPG, Percona, etc.) by specifying the appropriate GVR and parameters path.
Example for CNPG:
req := kubernetes.CRDPatchRequest{
Ctx: ctx,
Client: k8sClient,
GVR: schema.GroupVersionResource{
Group: "postgresql.cnpg.io",
Version: "v1",
Resource: "clusters",
},
ResourceName: "my-cluster",
ParametersPath: "spec.postgresql.parameters",
Parameters: params,
MaxRetries: 5,
RetryDelay: 5 * time.Second,
Logger: logger,
}
err := kubernetes.PatchCRDParameters(req)
Example for Percona:
req := kubernetes.CRDPatchRequest{
Ctx: ctx,
Client: k8sClient,
GVR: schema.GroupVersionResource{
Group: "pxc.percona.com",
Version: "v1",
Resource: "perconaxtradbclusters",
},
ResourceName: "my-cluster",
ParametersPath: "spec.pxc.configuration",
Parameters: params,
MaxRetries: 5,
RetryDelay: 5 * time.Second,
Logger: logger,
}
err := kubernetes.PatchCRDParameters(req)
func TriggerCNPGRollingRestart ¶
func TriggerCNPGRollingRestart(ctx context.Context, client Client, clusterName string, logger *log.Logger) error
TriggerCNPGRollingRestart triggers a rolling restart of a CNPG cluster by setting the restart annotation. This is the recommended way to apply restart-required PostgreSQL parameter changes.
func WaitForCNPGClusterHealthy ¶
func WaitForCNPGClusterHealthy(ctx context.Context, client Client, clusterName string, maxWait, pollInterval time.Duration, logger *log.Logger) error
WaitForCNPGClusterHealthy waits for a CNPG cluster to reach healthy state after rolling restart. It monitors the cluster's status.phase field and waits until it becomes "Cluster in healthy state". This is more reliable than watching individual pods because CNPG manages the restart sequence.
Types ¶
type CNPGClusterStatus ¶
type CNPGClusterStatus struct {
// Current primary pod name (e.g., "postgres-1")
CurrentPrimary string
// Target primary pod name during failover/switchover (e.g., "postgres-2")
TargetPrimary string
// Cluster phase (e.g., "Cluster in healthy state", "Failing over", "Switchover in progress")
Phase string
// Number of ready instances
ReadyInstances int64
// Total number of instances
Instances int64
}
CNPGClusterStatus contains key status fields from a CNPG Cluster resource
type CRDPatchRequest ¶
type CRDPatchRequest struct {
// Context for the operation
Ctx context.Context
// Kubernetes client with configuration
Client Client
// GroupVersionResource identifying the CRD (e.g., CNPG Cluster, Percona XtraDB Cluster)
GVR schema.GroupVersionResource
// Name of the specific resource to patch
ResourceName string
// JSON path where parameters should be set (e.g., "spec.postgresql.parameters")
ParametersPath string
// Map of parameter names to values (all values must be strings)
Parameters map[string]string
// Maximum number of retry attempts for concurrent operations
MaxRetries int
// Delay between retry attempts
RetryDelay time.Duration
// Logger for operation messages
Logger *log.Logger
}
CRDPatchRequest contains all parameters needed to patch a CRD resource with PostgreSQL parameters.
type Client ¶
type Client struct {
Namespace string
Config *rest.Config
Clientset *kubernetes.Clientset
MetricsClient *metricsv1.Clientset
}
func CreateClient ¶
CreateClient creates a Kubernetes client with auto-detection: 1. Try in-cluster config first (for when agent runs as a pod) 2. Fall back to kubeconfig file (configPath or default ~/.kube/config) Client also keeps track of namespace
func (*Client) ContainerClient ¶
func (c *Client) ContainerClient(podName string, containerName string) ContainerClient
func (*Client) FindCNPGPrimaryPod ¶
FindCNPGPrimaryPod finds the primary pod in a CNPG cluster by label selector. CNPG labels pods with cnpg.io/cluster=<cluster-name> and role=primary.
func (*Client) GetCNPGClusterStatus ¶
func (c *Client) GetCNPGClusterStatus(ctx context.Context, clusterName string) (*CNPGClusterStatus, error)
GetCNPGClusterStatus retrieves the status of a CNPG cluster from the Cluster CRD. This is more reliable than checking pod labels because it shows the cluster's actual state including failover/switchover in progress.
type ContainerClient ¶
type ContainerClient struct {
Namespace string
PodName string
ContainerName string
Clientset *kubernetes.Clientset
MetricsClient *metricsv1.Clientset
}
func (*ContainerClient) CPULimitCoresMilli ¶
func (cc *ContainerClient) CPULimitCoresMilli(ctx context.Context) (int64, error)
func (*ContainerClient) CPUUsageMillicores ¶
func (cc *ContainerClient) CPUUsageMillicores(ctx context.Context) (int64, error)
CPUUsageMillicores returns the current instantaneous CPU usage in millicores from metrics-server. This is NOT cumulative - it's a snapshot of current usage at the time of the call. 1 core = 1000 millicores.
func (*ContainerClient) DiskInfo ¶
func (cc *ContainerClient) DiskInfo(ctx context.Context) (*DiskInfo, error)
DiskInfo returns disk usage information for the container from cAdvisor.
func (*ContainerClient) GetContainerSystemInfo ¶
GetContainerSystemInfo gathers static system information from Kubernetes container This should be called once at startup or infrequently, as the values don't change often
func (*ContainerClient) IOStats ¶
func (cc *ContainerClient) IOStats(ctx context.Context) (*ContainerIOStats, error)
IOStats returns cumulative I/O statistics for the container. These are cumulative counters - to get rates, take the difference between two samples.
func (*ContainerClient) LoadAverage ¶
func (cc *ContainerClient) LoadAverage(ctx context.Context) (float64, error)
LoadAverage returns the system load average from the node.
func (*ContainerClient) MemoryLimitBytes ¶
func (cc *ContainerClient) MemoryLimitBytes(ctx context.Context) (int64, error)
func (*ContainerClient) MemoryUsageBytes ¶
func (cc *ContainerClient) MemoryUsageBytes(ctx context.Context) (int64, error)
MemoryUsageBytes returns the current memory usage in bytes.
func (*ContainerClient) NetworkStats ¶
func (cc *ContainerClient) NetworkStats(ctx context.Context) (*NetworkStats, error)
NetworkStats returns cumulative network statistics for the container from cAdvisor.
func (*ContainerClient) NodeOSInfo ¶
func (cc *ContainerClient) NodeOSInfo(ctx context.Context) (*NodeOSInfo, error)
NodeOSInfo returns operating system information from the node where the pod is running.
type ContainerIOStats ¶
type ContainerIOStats struct {
// Cumulative count of read operations completed
ReadsTotal uint64
// Cumulative count of write operations completed
WritesTotal uint64
// Cumulative bytes read
ReadBytesTotal uint64
// Cumulative bytes written
WriteBytesTotal uint64
// Timestamp from cAdvisor in milliseconds (used to detect stale metrics)
Timestamp int64
}
ContainerIOStats contains cumulative I/O statistics for a container from cAdvisor metrics.
type ContainerMetricsCache ¶
type ContainerMetricsCache struct {
PreviousCPUMillicores int64
PreviousMemoryBytes int64
PreviousReadBytesTotal uint64
PreviousWriteBytesTotal uint64
PreviousReadsTotal uint64
PreviousWritesTotal uint64
PreviousNetworkReceiveBytes uint64
PreviousNetworkSendBytes uint64
PreviousTimestamp time.Time
PreviousCAdvisorTimestamp int64 // Timestamp from cAdvisor metrics to detect stale data
Initialized bool
}
ContainerMetricsCache stores previous metric values for calculating deltas
type ContainerMetricsConfig ¶
ContainerMetricsConfig holds configuration for collecting container metrics
type DiskInfo ¶
type DiskInfo struct {
// Total disk space in bytes
TotalBytes uint64
// Used disk space in bytes
UsedBytes uint64
// Usage percentage (0-100)
UsedPercent float64
// Filesystem type (e.g., "ext4", "xfs", "overlay")
FilesystemType string
// Storage class name (e.g., "standard", "fast-ssd")
StorageClassName string
}
DiskInfo contains filesystem information for the container's volumes.
type NetworkStats ¶
type NetworkStats struct {
// Cumulative bytes received
ReceiveBytesTotal uint64
// Cumulative bytes transmitted
TransmitBytesTotal uint64
// Cumulative packets received
ReceivePacketsTotal uint64
// Cumulative packets transmitted
TransmitPacketsTotal uint64
}
NetworkStats contains cumulative network statistics for the container.
type NodeOSInfo ¶
type NodeOSInfo struct {
OSImage string // e.g., "Ubuntu 22.04.3 LTS"
KernelVersion string // e.g., "5.15.0-1048-gke"
OperatingSystem string // e.g., "linux"
Architecture string // e.g., "amd64"
ContainerRuntime string // e.g., "containerd://1.6.24"
KubeletVersion string // e.g., "v1.27.3-gke.100"
}
NodeOSInfo contains operating system information from the node.