cnpg-i-scale-to-zero

README

0️⃣ CNPG-I Scale-to-Zero Plugin

A CNPG-I plugin that automatically hibernates inactive CloudNativePG clusters to optimize resource usage and reduce costs.

Overview

This plugin monitors PostgreSQL database activity and automatically scales clusters down to zero replicas when they've been inactive for a configurable period. It injects a monitoring sidecar into the primary PostgreSQL pod that tracks database connections and query activity, then hibernates the cluster by setting the cnpg.io/hibernation annotation when the inactivity threshold is reached.

How It Works

1. Sidecar Injection: Automatically adds a monitoring sidecar to the primary PostgreSQL pod
2. Activity Monitoring: The sidecar periodically checks for active database connections and recent queries
3. Automatic Hibernation: When the cluster is inactive for the configured duration, it sets the hibernation annotation
4. Resource Optimization: Inactive clusters are scaled to zero, freeing up cluster resources

Installation

For detailed installation instructions, see INSTALL.md.

Quick start:

kubectl apply -f manifest.yaml

Container Images

The plugin consists of two container images:

• Plugin: ghcr.io/xataio/cnpg-i-scale-to-zero
• Sidecar: ghcr.io/xataio/cnpg-i-scale-to-zero-sidecar

Image Tags

We publish different image tags for different use cases:

Local Docker library

• dev: local docker images built using make docker-build-dev

GHCR

Development Tags

• main: Latest development build from the main branch
• main-<sha>: Specific commit builds from main branch

Release Tags

• latest: Latest stable release
• v1.0.0, v1.1.0, etc.: Specific version releases

Usage

Enable scale-to-zero for a PostgreSQL cluster by adding the plugin and configuration annotations:

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: my-cluster
  annotations:
    xata.io/scale-to-zero-enabled: "true"
    xata.io/scale-to-zero-inactivity-minutes: "10"
spec:
  instances: 3
  enableSuperuserAccess: true
  plugins:
    - name: cnpg-i-scale-to-zero.xata.io
  storage:
    size: 1Gi

Configuration

The plugin behavior is configured through cluster annotations:

• xata.io/scale-to-zero-enabled: Set to "true" to enable scale-to-zero functionality
• xata.io/scale-to-zero-inactivity-minutes: Sets the inactivity threshold in minutes before hibernation (default: 30 minutes)

The plugin automatically manages the cnpg.io/hibernation annotation to trigger cluster hibernation.

See the cluster example for a complete configuration.

RBAC

Important: Each cluster that uses scale-to-zero functionality requires specific RBAC permissions for the sidecar to update cluster resources.

Create the required RBAC using the template:

# Copy the RBAC template
curl -O https://raw.githubusercontent.com/xataio/cnpg-i-scale-to-zero/main/doc/examples/rbac-template.yaml

# Edit the template to replace CLUSTER_NAME and NAMESPACE
sed -i 's/CLUSTER_NAME/my-cluster/g; s/NAMESPACE/default/g' rbac-template.yaml

# Apply the RBAC configuration
kubectl apply -f rbac-template.yaml

Or see the RBAC template for manual customization.

Monitoring and Observability

The plugin provides logging to help monitor its operation:

• Sidecar injection events are logged during pod creation
• Activity monitoring status is logged at each check interval
• Hibernation events are logged when clusters are scaled down

You can view the plugin logs using:

kubectl logs -n cnpg-system deployment/cnpg-i-scale-to-zero-plugin

And monitor the sidecar logs in the PostgreSQL pods:

kubectl logs <pod-name> -c scale-to-zero

Development

For local development and building from source:

# Build binaries
make build

# Build Docker images
make docker-build-dev

# Run tests and linting
make test
make lint

# Local development with kind
make kind-deploy-dev

This plugin uses the pluginhelper from cnpg-i-machinery to simplify the plugin's implementation.

For additional details on the plugin implementation, refer to the development documentation.