[2026-05-16-llmstxt-pg-docs] docs: add llms.txt index for LLM context

llms.txt

@@ -0,0 +1,44 @@
+# Alauda support for PostgreSQL
+
+> Kubernetes-native PostgreSQL management solution built on the Zalando Postgres Operator. Automates deployment, high availability, failover, scaling, backup and recovery, and monitoring of PostgreSQL clusters via CRDs.
+
+## Root
+
+- [docs/en/architecture.mdx](docs/en/architecture.mdx): Reference architecture for the PostgreSQL Operator (built on the Zalando Postgres Operator), detailing the four core components: the Operator Controller that reconciles PostgreSQL CRDs, Patroni for HA and failover, Spilo as the PostgreSQL container image, and Prometheus/Grafana monitoring. Also documents the RBAC model with least-privilege operator permissions, runtime-created ServiceAccounts and RoleBindings, user-facing roles (admin, edit, view, backup, restore) with role aggregation to cpaas.io platform roles, and supported deployment modes (single-cluster, multi-cluster, and high-availability).
+- [docs/en/index.mdx](docs/en/index.mdx): Top-level navigation landing page for the Alauda support for PostgreSQL documentation, rendering an auto-generated Overview component that links into the introduction, installation, upgrade, architecture, API reference, and functions sections.
+- [docs/en/installation.mdx](docs/en/installation.mdx): Step-by-step installation guide for deploying Alauda support for PostgreSQL on the Alauda Container Platform, covering three plugin installations through the Marketplace and Operator Hub: Data Services Essentials, Data Services RDS Framework, and the PostgreSQL operator itself. Documents recommended Channel/Version/Installation Mode/Upgrade Strategy parameters and how to enable the `middleware-rds-postgresql` and `middleware-rds-postgresql-backup` Alpha feature gates at `/console-platform/feature-gate` so the PostgreSQL management UI appears under Data Services.
+- [docs/en/intro.mdx](docs/en/intro.mdx): Product introduction explaining that Alauda support for PostgreSQL is a Kubernetes-native solution built on the Zalando Postgres Operator that manages PostgreSQL clusters via CRDs. Lists key capabilities (operator-driven automation, Patroni-based HA and failover, horizontal/vertical scaling, backup/PITR to S3-compatible storage like AWS S3, GCS, Azure Blob, and MinIO, TLS, RBAC, Prometheus metrics) and limitations: PostgreSQL 14/16 only (11/12 removed), up to 15 replicas per cluster, Kubernetes 1.19+, dynamic-provisioning StorageClass, and a 2 CPU / 4 GB minimum per node.
+- [docs/en/release_notes.mdx](docs/en/release_notes.mdx): Release notes for v4.2.0, listing new and optimized features (deploying Postgres instances in PSA-restricted mode, Load Balancer Service type for hot-standby cluster replication, CVE fixes, and removal of PostgreSQL 11 and 12 support) along with placeholders for fixed and known issues from the Middleware project bug tracker.
+- [docs/en/upgrade.mdx](docs/en/upgrade.mdx): Upgrade guidance noting that PostgreSQL 11 and 12 are removed in v4.2.0 so clusters must be moved to PostgreSQL 14 or 16 first, and explaining the two operator upgrade strategies: Automatic (upgrade triggered as soon as a new component version is detected) and Manual (requires explicit approval).
+
+## apis
+
+- [docs/en/apis/index.mdx](docs/en/apis/index.mdx): Top-level API Reference landing page that renders an Overview component aggregating the Kubernetes APIs subtree (CRDs for postgresqls, postgresbackups, and postgresrestores).
+- [docs/en/apis/kubernetes_apis/index.mdx](docs/en/apis/kubernetes_apis/index.mdx): Index page for the Kubernetes APIs section, rendering an Overview component that links into the PostgreSQL CRD reference (postgresqls, postgresbackups, postgresrestores).
+- [docs/en/apis/kubernetes_apis/postgres/index.mdx](docs/en/apis/kubernetes_apis/postgres/index.mdx): Index page for the PostgreSQL APIs group, rendering an Overview component that surfaces the three CRDs documented under this section: postgresqls.acid.zalan.do, postgresbackups.middleware.alauda.io, and postgresrestores.middleware.alauda.io.
+- [docs/en/apis/kubernetes_apis/postgres/postgresbackup.mdx](docs/en/apis/kubernetes_apis/postgres/postgresbackup.mdx): Auto-generated CRD reference for `postgresbackups.middleware.alauda.io`, rendered via the `K8sCrd` component to expose the full schema (spec/status fields, validations, defaults) used to declare on-demand and scheduled PostgreSQL backups stored on S3-compatible object storage.
+- [docs/en/apis/kubernetes_apis/postgres/postgresqls.mdx](docs/en/apis/kubernetes_apis/postgres/postgresqls.mdx): Auto-generated CRD reference for `postgresqls.acid.zalan.do`, the core Zalando Postgres Operator resource, rendered via the `K8sCrd` component to surface all spec fields used to declare a PostgreSQL cluster (version, replica count, resources, volume, Patroni tuning, users, databases, parameters, etc.) and its status.
+- [docs/en/apis/kubernetes_apis/postgres/postgresrestores.mdx](docs/en/apis/kubernetes_apis/postgres/postgresrestores.mdx): Auto-generated CRD reference for `postgresrestores.middleware.alauda.io`, rendered via the `K8sCrd` component to expose the schema for restoring PostgreSQL clusters from a `PostgresBackup`, including source selection and point-in-time recovery (PITR) options.
+
+## functions
+
+- [docs/en/functions/01_create_instance.mdx](docs/en/functions/01_create_instance.mdx): Walk-through for creating PostgreSQL instances either via CLI (`kubectl create` against the `acid.zalan.do/v1` `postgresql` kind) or the web console. Provides full single-node and 3-replica HA YAML examples covering `numberOfInstances`, PostgreSQL 14/16 version selection, CPU/memory `resources`, `volume` size and StorageClass, Patroni TTL/loop_wait/retry_timeout, PSA-restricted security settings (`spiloRunAsUser/Group`, `restrictedPsaEnabled`), and `enableExporter` for Prometheus metrics; includes prerequisites, architecture recommendations, and production caveats.
+- [docs/en/functions/02_delete_instance.mdx](docs/en/functions/02_delete_instance.mdx): Procedure for deleting a PostgreSQL instance via `kubectl delete postgresql <name>` or the web console Actions menu, warning that deletion is irreversible and cascades to the StatefulSet, Pods, ConfigMaps, Secrets, PVCs, and monitoring/logging resources. Includes post-deletion verification commands (`kubectl get postgresql`, `kubectl get pvc`) and cross-links to backup, restore, and troubleshooting documentation.
+- [docs/en/functions/03_details.mdx](docs/en/functions/03_details.mdx): Guide for inspecting a running PostgreSQL instance from the CLI or web console, showing how to retrieve the cluster spec (`kubectl get postgresql -o yaml`), fetch user credentials from the `<instance>.credentials.postgresql.acid.zalan.do` Secret, find the read-write/read-only Service endpoints, view pod resource limits and the `pgdata-<instance>-0` PVC, and check node affinity/tolerations. Documents the UI instance detail page sections (basic info, configuration, scheduling) and notes that some fields are immutable after creation.
+- [docs/en/functions/15_back_restore.mdx](docs/en/functions/15_back_restore.mdx): Walks through storage-based physical backup and point-in-time restore for PostgreSQL instances using the `PostgresBackup` and `PostgresRestore` CRDs (apiVersion `middleware.alauda.io/v1`), including configuring S3-compatible backup storage with bucket, namespace, and `retainDay` retention on the `postgresql` resource. Covers both kubectl CLI manifests (specifying `backupCluster`, `targetCluster` Zalando `postgresql` spec, and a `timestamp` for PITR) and the Web Console flow under the Backup and Restore tab, plus a reference table of backup status fields (`backupName`, `clusterUid`, `startLsn`/`finishLsn`, `executeNode`, `pgVersion`, `state`) and operational precautions around storage class compatibility and restore-time write isolation.
+- [docs/en/functions/18_scheduling.mdx](docs/en/functions/18_scheduling.mdx): Explains how to pin PostgreSQL instance pods to dedicated nodes using Kubernetes node labels and pod tolerations configured in the Scheduling Configuration section of the instance creation page, with a worked example placing instances on nodes 192.168.100.103-105 labeled `keypostgres=valuepostgres` and tainted with the same key. Includes a reference of taint `effect` semantics (`NoSchedule`, `PreferNoSchedule`, `NoExecute`) and toleration operators (`Equal`, `Exists`), plus prerequisites for platform administrators to apply node labels and taints before scheduling, and a verification path via Container Platform > Compute Components > Container Groups.
+- [docs/en/functions/25_log.mdx](docs/en/functions/25_log.mdx): Shows how to access PostgreSQL container-level logs for troubleshooting instance events and errors, using `kubectl get pod -l "middleware.instance/name=${instance_name}"` to locate instance pods and `kubectl logs <pod> -c postgres` to read the `postgres` container's output, or the Logs tab in the Web Console under the instance detail page. Notes that PostgreSQL writes logs to `/var/log/pg_log` inside the container by default as `.log` or `.csv` files, subject to PostgreSQL configuration.
+- [docs/en/functions/35_monitor.mdx](docs/en/functions/35_monitor.mdx): Describes the built-in monitoring panel for PostgreSQL instances, covering resource, performance, and capacity metrics surfaced in the instance's Monitoring tab and usable for alerting and notification policies. Catalogs the default metrics collected (CPU utilization, memory usage, file descriptors, connection count vs. max_connections, transaction commit/rollback rates, SELECT/INSERT/UPDATE/DELETE query counts, cache hit rate, table-level lock contention, temporary file size, checkpoint frequency, conflicts/deadlocks, background writer buffer stats) with guidance such as keeping cache hit rate above 95% and enabling the PostgreSQL statistics collector for some metrics.
+- [docs/en/functions/index.mdx](docs/en/functions/index.mdx): Landing page for the Feature Guide (Guides) section of the Alauda PostgreSQL documentation; renders an `<Overview />` component that lists the per-feature subtopics such as backup and restore, scheduling configuration, logs, and monitoring.
+
+## how_to
+
+- [docs/en/how_to/configure_ha_cluster.mdx](docs/en/how_to/configure_ha_cluster.mdx): End-to-end recipe for deploying a highly available PostgreSQL cluster on Kubernetes using the Zalando `acid.zalan.do/v1` `postgresql` CRD with Patroni-managed failover, including a 3-instance manifest setting `synchronous_mode: true`, `synchronous_node_count: 2`, custom `pg_hba`, PostgreSQL parameters (`shared_buffers`, `work_mem`), volume IOPS, scheduled S3 backups, and optional PgBouncer-style connection pooler and Prometheus exporter sidecars. Documents key Patroni tuning parameters (`ttl`, `loop_wait`, `retry_timeout`, `maximum_lag_on_failover`), verification commands (`patronictl list`, `pg_stat_replication`), failover testing by deleting the primary pod, plus a Web Console flow and best practices for SSD storage, alert thresholds, and synchronous replica counts.
+- [docs/en/how_to/index.mdx](docs/en/how_to/index.mdx): Landing page for the HowTo section of the Alauda PostgreSQL documentation; renders an `<Overview />` component that links to task-oriented guides such as configuring a high availability PostgreSQL cluster.
+
+## trouble_shooting
+
+- [docs/en/trouble_shooting/backup_failure.mdx](docs/en/trouble_shooting/backup_failure.mdx): Diagnostic playbook for `PostgresBackup` and restore failures that present as stuck backup tasks, restore errors, or data inconsistency, attributed to storage misconfiguration, permission errors, network failures, or insufficient resources. Provides triage commands (`kubectl get postgresbackup -o yaml` for `spec.storage`/`status.state`/`status.message`, backup pod logs, `s3cmd ls s3://<bucket>` to verify storage reachability, `kubectl top pod` for resource pressure) and remediations covering S3 bucket permissions, IAM roles, Kubernetes Secrets for access keys, network policy review, and resource quota adjustments, plus preventive practices like periodic restore drills and retention policy review.
+- [docs/en/trouble_shooting/cluster_creation_failure.mdx](docs/en/trouble_shooting/cluster_creation_failure.mdx): Troubleshooting guide for PostgreSQL clusters that remain stuck in the Creating phase before failing, attributing root causes to storage misconfiguration, namespace resource quota exhaustion, network connectivity issues, and container image pull errors. Walks through diagnostic commands for each area (`kubectl describe pvc` for storage class and PVC binding, `kubectl describe quota` for CPU/memory/pod limits, `kubectl get endpoints` for service reachability, `kubectl describe pod` for image pull failures and registry auth) along with remediation steps for storage class validation, quota adjustments, network policy review, and image registry credentials.
+- [docs/en/trouble_shooting/failover_issues.mdx](docs/en/trouble_shooting/failover_issues.mdx): Troubleshooting guide for abnormal master-slave (primary-replica) switchover in Patroni-managed PostgreSQL clusters that result in prolonged failover time, data inconsistency, or service interruption due to network partitions, slow storage, misconfiguration, or resource shortage. Covers inspecting cluster state via `kubectl get postgresql -o yaml` (`status.PostgresClusterStatus`, `status.master`, `status.pods`), reading the `patroni` container logs for leader election events, querying `pg_stat_replication` for `state`/`sync_state`/`replay_lag`, and tuning fixes such as Patroni `ttl`/`loop_wait`/`retry_timeout` and PostgreSQL `wal_keep_segments`/`max_wal_senders` plus scaling and network policy remediation.
+- [docs/en/trouble_shooting/index.mdx](docs/en/trouble_shooting/index.mdx): Landing page for the Trouble Shooting section of the Alauda PostgreSQL documentation; renders an `<Overview />` component that links to failure-mode runbooks such as cluster creation failure, backup and restore failure, and master-slave switch exceptions.

llmstxt-config.yaml

@@ -0,0 +1,24 @@
+# llms.txt generator configuration for alauda/pg-docs
+# Product: Alauda support for PostgreSQL (Kubernetes-native PostgreSQL operator)
+
+project_name: "Alauda support for PostgreSQL"
+summary: "Kubernetes-native PostgreSQL management solution built on the Zalando Postgres Operator. Automates deployment, high availability, failover, scaling, backup and recovery, and monitoring of PostgreSQL clusters via CRDs."
+
+include_patterns:
+  - "docs/**/*.md"
+  - "docs/**/*.mdx"
+
+exclude_patterns:
+  - "**/node_modules/**"
+  - "**/.git/**"
+  - "**/llms.txt"
+  - "**/CHANGELOG.md"
+  - "**/CONTRIBUTING.md"
+  - "README.md"
+
+# Group H2 sections by the first path segment under docs/en/.
+# e.g. docs/en/apis/index.mdx -> group "apis"; docs/en/architecture.mdx -> "Root"
+grouping_base_path: "docs/en"
+
+batch_size: 15
+description_max_words: 150