Xây Dựng PostgreSQL High Availability Cluster với Ansible

Giới Thiệu

High Availability (HA) là yêu cầu thiết yếu đối với bất kỳ hệ thống database nào trong môi trường production. Tuy nhiên, việc triển khai một PostgreSQL HA cluster từ đầu thường đòi hỏi nhiều thời gian nghiên cứu, dễ xảy ra sai sót trong quá trình cấu hình thủ công, và khó khăn trong việc duy trì tính nhất quán giữa các môi trường.

Bài viết này chia sẻ kinh nghiệm của chúng tôi trong việc phát triển một giải pháp automation hoàn chỉnh sử dụng Ansible, giúp triển khai PostgreSQL HA cluster một cách nhanh chóng và đáng tin cậy. Sau khi sử dụng thành công trong production, chúng tôi quyết định open-source giải pháp này cho cộng đồng.

Repository: postgres-patroni-etcd-install

Các Tính Năng Chính

Automation & Deployment

• Triển khai tự động toàn bộ cluster với một lệnh duy nhất
• Configuration as Code với hơn 70 biến môi trường được quản lý tập trung
• Hỗ trợ multi-environment (development, staging, production)

High Availability

• Auto-failover với Patroni (thời gian chuyển đổi 30-45 giây)
• Streaming replication với PostgreSQL 18.1
• Tự động khôi phục node bị lỗi với pg_rewind

Performance & Scalability

• Connection pooling với PgBouncer (tỷ lệ multiplexing 13:1)
• Hỗ trợ load balancing cho read queries
• Tối ưu hóa cho hệ thống với RAM từ 16GB đến 64GB+

DevOps Integration

• CI/CD pipeline với GitHub Actions
• Automated testing và validation
• Security scanning tích hợp

Bối Cảnh và Động Lực Phát Triển

Vấn Đề Thực Tế

Trong quá trình vận hành hệ thống production, chúng tôi đã trải qua một sự cố nghiêm trọng khi PostgreSQL server gặp lỗi phần cứng vào lúc 2 giờ sáng. Kết quả là toàn bộ ứng dụng ngừng hoạt động, và phải mất 45 phút để khôi phục từ backup. Sự cố này không chỉ gây thiệt hại về mặt doanh thu mà còn ảnh hưởng đến uy tín và niềm tin của khách hàng.

Thách Thức Khi Triển Khai HA

Sau sự cố, chúng tôi quyết định triển khai giải pháp High Availability. Tuy nhiên, việc cấu hình thủ công gặp phải nhiều khó khăn:

Độ phức tạp cao: Cần hiểu sâu về PostgreSQL replication, Patroni, etcd, và các tương tác giữa chúng. Quá trình nghiên cứu và cấu hình kéo dài 2-3 ngày cho một engineer có kinh nghiệm.

Rủi ro sai sót: Cấu hình thủ công dễ dẫn đến inconsistency giữa các nodes, gây ra các vấn đề khó debug. Một sai sót nhỏ trong file config có thể khiến toàn bộ cluster không hoạt động đúng.

Khó maintain: Khi cần update configuration hoặc scale cluster, phải thực hiện thủ công trên từng node, tốn thời gian và dễ sai sót.

Thiếu documentation: Không có tài liệu chi tiết về quá trình setup, khiến việc onboard engineer mới vào dự án trở nên khó khăn.

Giải Pháp

Chúng tôi đã phát triển một bộ Ansible playbooks để giải quyết các vấn đề trên:

Infrastructure as Code: Toàn bộ cấu hình được version control, dễ dàng review và rollback khi cần.

Repeatable Deployment: Có thể triển khai cluster giống hệt nhau trên nhiều môi trường khác nhau (dev, staging, production) chỉ bằng cách thay đổi file .env.

Self-documenting: Code Ansible rõ ràng, kèm theo README chi tiết, giúp team mới dễ dàng hiểu và sử dụng.

CI/CD Integration: Tự động validate configuration trước khi deploy, giảm thiểu rủi ro lỗi.

Sau khi sử dụng thành công trong production trong hơn 6 tháng, chúng tôi quyết định open-source giải pháp này để chia sẻ với cộng đồng.

Kiến Trúc Hệ Thống

Tech Stack

Giải pháp sử dụng các công nghệ được kiểm chứng trong cộng đồng:

Kiến Trúc Tổng Quan

┌─────────────────────────────────────┐
│       Application Layer             │
│  (Spring Boot / Django / Node.js)   │
└──────────────┬──────────────────────┘
               │ Port 6432 (PgBouncer)
        ┌──────┴──────┬──────────┐
        ▼             ▼          ▼
   ┌────────┐    ┌────────┐   ┌────────┐
   │PgBouncer│   │PgBouncer│  │PgBouncer│
   │Node 1   │   │Node 2   │  │Node 3   │
   └────┬───┘    └────┬───┘   └────┬───┘
        │ Port 5432   │             │
   ┌────▼────┐   ┌───▼────┐   ┌────▼────┐
   │PostgreSQL│  │PostgreSQL│ │PostgreSQL│
   │ PRIMARY │  │ REPLICA  │ │ REPLICA  │
   │Read/Write│  │Read Only│ │Read Only │
   └────┬────┘   └────┬────┘  └────┬────┘
        │ Port 8008   │             │
   ┌────▼────┐   ┌────▼────┐  ┌────▼────┐
   │ Patroni │   │ Patroni │  │ Patroni │
   │HA Mgr   │   │HA Mgr   │  │ HA Mgr  │
   └────┬────┘   └────┬────┘  └────┬────┘
        │ Port 2379   │             │
        └──────┬──────┴─────────────┘
               ▼
        ┌──────────────────┐
        │   etcd Cluster   │
        │ (Leader Election)│
        └──────────────────┘

Giải Thích Các Thành Phần

PgBouncer Layer: Được deploy trên mỗi node để cung cấp connection pooling. Application có thể connect đến bất kỳ node nào, giảm single point of failure và network latency.

PostgreSQL Cluster: Sử dụng streaming replication với một primary node (read/write) và hai replica nodes (read-only). Patroni quản lý toàn bộ lifecycle của cluster.

Patroni: Đóng vai trò là HA orchestrator, thực hiện health check liên tục, tự động failover khi primary bị lỗi, và đảm bảo data consistency thông qua distributed consensus.

etcd Cluster: Lưu trữ cấu hình cluster và thực hiện leader election. Đảm bảo chỉ có một primary node tại mỗi thời điểm, tránh split-brain scenario.

Tại Sao 3 Nodes?

Số lượng 3 nodes là minimum cho một HA cluster do:

• Quorum: etcd cần ít nhất 3 nodes để đạt được quorum (2/3) và tolerate 1 node failure
• Cost-effective: Đủ để đảm bảo HA mà không quá tốn kém về infrastructure
• Proven pattern: Là số lượng standard được recommend bởi cộng đồng PostgreSQL và etcd

Hướng Dẫn Triển Khai

Yêu Cầu Hệ Thống

Hardware (mỗi node)

Minimum cho môi trường lab/development:

• CPU: 2 cores
• RAM: 4 GB
• Disk: 20 GB (OS) + 20 GB (Data)
• Network: 1 Gbps

Recommended cho production:

• CPU: 4-8 cores
• RAM: 16-32 GB
• Disk: 50 GB SSD (OS) + 100+ GB NVMe SSD (Data)
• Network: 10 Gbps

Software

Control node (máy chạy Ansible):

• Ansible >= 2.12
• Python >= 3.9

Target nodes:

• Ubuntu 22.04 LTS / Debian 12 / Rocky Linux 9
• SSH access với root hoặc sudo privileges
• Python 3.x installed

Các Bước Triển Khai

Bước 1: Chuẩn Bị Repository

git clone https://github.com/xdev-asia-labs/postgres-patroni-etcd-install.git
cd postgres-patroni-etcd-install

Bước 2: Cấu Hình Environment

Tạo file cấu hình từ template:

cp .env.example .env

Chỉnh sửa các thông số quan trọng:

# Địa chỉ IP của các nodes
NODE1_IP=10.0.0.11
NODE2_IP=10.0.0.12
NODE3_IP=10.0.0.13

# Mật khẩu PostgreSQL (bắt buộc phải thay đổi)
POSTGRESQL_SUPERUSER_PASSWORD=your_strong_password_here
POSTGRESQL_REPLICATION_PASSWORD=your_replication_password_here

# Performance tuning (ví dụ cho server 16GB RAM)
POSTGRESQL_SHARED_BUFFERS=4GB
POSTGRESQL_EFFECTIVE_CACHE_SIZE=12GB
POSTGRESQL_MAX_CONNECTIONS=100
PGBOUNCER_MAX_CLIENT_CONN=1000

Bước 3: Cấu Hình Inventory

Chỉnh sửa inventory/hosts.yml:

all:
  children:
    postgres:
      hosts:
        pg-node1:
          ansible_host: 10.0.0.11
          patroni_name: node1

Bước 4: Triển Khai Cluster

# Load environment variables
set -a && source .env && set +a

# Deploy cluster
ansible-playbook playbooks/site.yml -i inventory/hosts.yml

Bước 5: Xác Minh

ssh root@10.0.0.11 "patronictl -c /etc/patroni/patroni.yml list"

Tính Năng Nổi Bật

Configuration as Code

Toàn bộ configuration được quản lý trong file .env với hơn 70 variables, giúp:

• Dễ dàng quản lý và audit configuration
• Chuyển đổi giữa các môi trường chỉ bằng cách swap file .env
• Bảo mật tốt hơn với .gitignore cho sensitive data
• Developer-friendly, không cần hiểu sâu về Ansible

Connection Pooling

PgBouncer được cấu hình để tối ưu hóa kết nối:

• Tỷ lệ multiplexing 13:1 (3000 client → 225 backend connections)
• Automatic failover với multi-host support
• Giảm memory và CPU overhead trên PostgreSQL

Zero-Downtime Operations

Planned Switchover: Chuyển đổi primary node một cách có kế hoạch với downtime chỉ 2-5 giây.

Automatic Failover: Tự động failover trong 30-45 giây khi primary bị lỗi.

Rolling Updates: Update cấu hình hoặc version mà không ảnh hưởng đến service availability.

CI/CD Pipeline

Automated Validation

GitHub Actions tự động validate mỗi thay đổi:

• YAML syntax checking
• Ansible playbooks validation
• Security scanning (Trivy, TruffleHog)
• Code quality checks

Release Automation

Khi tạo tag mới (v1.0.0), GitHub Actions tự động:

• Generate changelog từ git history
• Tạo release archive
• Publish GitHub Release với documentation

Performance

Trong môi trường test với 3 nodes (16GB RAM, 5 cores mỗi node):

• Read QPS: 50,000-100,000
• Write QPS: 10,000-20,000
• Failover time: 30-45 seconds
• Connection capacity: 3,000 clients
• Query latency: <5ms (simple queries)

Bài Học Kinh Nghiệm

1. Sử Dụng Proven Tools

Thay vì tự phát triển, chúng tôi sử dụng các công nghệ đã được kiểm chứng như Patroni, etcd, và PgBouncer. Điều này giúp tập trung vào automation thay vì reinvent the wheel.

2. Configuration as Code

Externalize configuration ra .env file thay vì hardcode trong playbooks giúp dễ dàng customize và maintain cho different environments.

3. Security First

Luôn prioritize security từ đầu:

• Sử dụng .gitignore cho sensitive files
• Generate strong passwords
• Tự động configure firewall rules
• Tích hợp security scanning trong CI

4. Documentation Matters

Documentation tốt giảm onboarding time và thể hiện sự professional của dự án. Chúng tôi maintain documentation đầy đủ bằng cả English và Vietnamese.

Roadmap

Các tính năng đang phát triển:

• Tích hợp Prometheus/Grafana monitoring
• Automated backup với pgBackRest
• Terraform support cho cloud deployment
• Docker/Kubernetes deployment option
• Multi-region replication

Khi Nào Nên Sử Dụng

Phù hợp với:

• Applications yêu cầu high availability (uptime > 99.9%)
• Hệ thống không thể tolerate extended downtime
• Multi-tenant applications với nhiều concurrent connections
• Teams áp dụng Infrastructure as Code

Không cần thiết khi:

• Development/testing environments đơn giản
• Low-traffic applications
• Applications có thể accept occasional downtime
• Budget constraints (cần ít nhất 3 servers)

Kết Luận

Việc xây dựng một PostgreSQL High Availability cluster không còn là thách thức lớn nếu có đúng tools và phương pháp tiếp cận. Giải pháp này đã được kiểm chứng trong production và giúp đảm bảo uptime cho nhiều hệ thống quan trọng.

Với bộ Ansible playbooks này, bạn có thể triển khai production-ready cluster trong 10 phút, đạt được uptime trên 99.9%, và quản lý infrastructure theo phương pháp Infrastructure as Code.

Đóng Góp

Nếu bạn thấy dự án hữu ích:

• ⭐ Star repository
• 🐛 Report issues
• 💬 Share feedback
• 🤝 Contribute code
• 📢 Share với cộng đồng