Skip to content

Commit 2b500ef

Browse files
levkklevkk
authored
More ee docs (#89)
1 parent 181aad6 commit 2b500ef

12 files changed

Lines changed: 280 additions & 27 deletions

File tree

‎.github/workflows/ci.yaml‎

Lines changed: 5 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -8,30 +8,14 @@ jobs:
88
verify-tomls:
99
runs-on: blacksmith-4vcpu-ubuntu-2404
1010
timeout-minutes: 30
11+
env:
12+
PGDOG_IMAGE: ghcr.io/pgdogdev/pgdog-enterprise:main-ent
1113
steps:
1214
- name: Checkout code
1315
uses: actions/checkout@v4
14-
- name: Checkout pgdog-enterprise
15-
uses: actions/checkout@v4
16-
with:
17-
repository: pgdogdev/pgdog-enterprise
18-
ref: main-ent
19-
path: pgdog-source
20-
token: ${{ secrets.PGDOG_ENTERPRISE_TOKEN }}
21-
- uses: actions-rs/toolchain@v1
22-
with:
23-
toolchain: stable
24-
override: true
25-
- name: Install CMake 3.31
26-
run: |
27-
sudo apt update && sudo apt install mold -y
28-
sudo apt remove cmake
29-
sudo pip3 install cmake==3.31.6
30-
cmake --version
31-
- name: Build
32-
run: cargo build
33-
working-directory: pgdog-source
16+
- name: Pull PgDog Enterprise image
17+
run: docker pull "$PGDOG_IMAGE"
3418
- name: Install test dependencies
3519
run: sudo pip3 install -r tests/requirements.txt
3620
- name: Run tests
37-
run: python3 tests/test_code_blocks.py pgdog-source/target/debug/pgdog
21+
run: python3 tests/test_code_blocks.py tests/pgdog-docker.sh

‎docs/enterprise_edition/control_plane/.pages‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
nav:
2+
- index.md
3+
- installation.md
4+
- features
5+
- ...

‎docs/enterprise_edition/control_plane/features/.pages‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
nav:
2+
- index.md
3+
- ...

‎docs/enterprise_edition/control_plane/features/alerts.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
icon: material/alert-circle-outline
3+
---
4+
5+
# Alerts
6+
7+
Since the control plane has access to real-time PgDog [metrics](../../../features/metrics.md), it can detect outliers and trigger automatic alerts.
8+
9+
## How it works
10+
11+
The control plane evaluates the metrics it receives from all PgDog instances on a continuous loop. When they exceed pre-configured thresholds, an incident
12+
is created using one of the configured integrations.
13+
14+
<center>
15+
<img src="/images/ee/alerts.png" width="100%" alt="Alerts">
16+
</center>
17+
18+
### Integrations
19+
20+
The following incident management providers are supported:
21+
22+
| Provider | Description |
23+
|-|-|
24+
| [incident.io](https://incident.io/) | The control plane will create an incident with the highest available priority. |
25+
26+
### Configuration
27+
28+
Alerts are **disabled** by default. To enable them, configure a provider's API key and set thresholds for each supported metric you would like to monitor:
29+
30+
```yaml title="values.yaml"
31+
control:
32+
config:
33+
alerts:
34+
evaluation_window_secs: 300
35+
thresholds:
36+
clients_waiting: 10
37+
cpu: 90.0
38+
memory: 2048
39+
server_connections: 100
40+
incident_io:
41+
api_key: inc_live_xxx
42+
```
43+
44+
#### Parameters
45+
46+
!!! note "Disabled by default"
47+
Thresholds have no defaults. If a threshold is not configured, its metric will not be monitored.
48+
49+
50+
The following parameters are configurable via the [Helm chart](../installation.md):
51+
52+
| Parameter | Description | Unit |
53+
|-|-|-|
54+
| `evaluation_window_secs` | The metrics evaluation window. Metrics are averaged over this period to produce an alert signal. | Seconds, e.g., `300` (5 minutes) |
55+
| `clients_waiting` | Average number of clients waiting for a connection from a pool. | Clients, e.g., `10` |
56+
| `cpu` | Average CPU utilization of each PgDog pod. | Percentage, e.g., `90.0` (90%) |
57+
| `memory` | Average memory utilization of each PgDog pod. | MiB, e.g., `2048` (2048 MiB) |
58+
| `server_connections` | Average number of open connections from PgDog to Postgres. | Connections, e.g., `100` |
59+
60+
#### Evaluation window
61+
62+
Longer evaluation windows reduce the chance of false positives in spiky workloads. Shorter windows will be evaluated quicker and will trigger faster notifications in case of an incident.

‎docs/enterprise_edition/control_plane/features/autoscaling.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
icon: material/arrow-expand-all
3+
---
4+
5+
# Autoscaling
6+
7+
Autoscaling automatically adjusts PgDog settings when the number of processes (e.g. pods in Kubernetes) in the same deployment changes. This simplifies configuration: you no longer need to perform manual calculations to resize connection pools.
8+
9+
## Configuration
10+
11+
Autoscaling is **disabled** by default. To enable it, add the following settings to the [control plane](../installation.md) Helm [chart](https://github.com/pgdogdev/helm-ee):
12+
13+
```yaml title="values.yaml"
14+
control:
15+
config:
16+
autoscaling:
17+
pool_size: true
18+
```
19+
20+
## How it works
21+
22+
When a PgDog process connects to the [control plane](../../control_plane/index.md), the control plane provides it with the total number of processes that are part of the same deployment. PgDog then automatically adjusts its configuration by dividing all pool-related configuration values by that number, for example:
23+
24+
=== "Configuration"
25+
```toml title="pgdog.toml"
26+
[general]
27+
default_pool_size = 200
28+
29+
[[databases]]
30+
name = "prod"
31+
host = "10.0.0.1"
32+
min_pool_size = 50
33+
```
34+
35+
```toml title="users.toml"
36+
[[users]]
37+
name = "postgres"
38+
database = "prod"
39+
pool_size = 100
40+
```
41+
42+
=== "2 processes"
43+
```toml title="pgdog.toml"
44+
[general]
45+
default_pool_size = 100
46+
47+
[[databases]]
48+
name = "prod"
49+
host = "10.0.0.1"
50+
min_pool_size = 25
51+
```
52+
53+
```toml title="users.toml"
54+
[[users]]
55+
name = "postgres"
56+
database = "prod"
57+
pool_size = 50
58+
```
59+
60+
=== "4 processes"
61+
```toml title="pgdog.toml"
62+
[general]
63+
default_pool_size = 50
64+
65+
[[databases]]
66+
name = "prod"
67+
host = "10.0.0.1"
68+
min_pool_size = 12
69+
```
70+
71+
```toml title="users.toml"
72+
[[users]]
73+
name = "postgres"
74+
database = "prod"
75+
pool_size = 25
76+
```
77+
78+
=== "8 processes"
79+
```toml title="pgdog.toml"
80+
[general]
81+
default_pool_size = 25
82+
83+
[[databases]]
84+
name = "prod"
85+
host = "10.0.0.1"
86+
min_pool_size = 6
87+
```
88+
89+
```toml title="users.toml"
90+
[[users]]
91+
name = "postgres"
92+
database = "prod"
93+
pool_size = 12
94+
```
95+
96+
### Supported settings
97+
98+
The following configuration options are supported for pool size autoscaling:
99+
100+
| Section | Configuration |
101+
|-|-|
102+
| [`[general]`](../../../configuration/pgdog.toml/general.md) | [`default_pool_size`](../../../configuration/pgdog.toml/general.md#default_pool_size) (alias: `max_pool_size`) |
103+
| [`[general]`](../../../configuration/pgdog.toml/general.md) | [`min_pool_size`](../../../configuration/pgdog.toml/general.md#min_pool_size) |
104+
| [`[[databases]]`](../../../configuration/pgdog.toml/databases.md) | [`pool_size`](../../../configuration/pgdog.toml/databases.md#pool_size) |
105+
| [`[[databases]]`](../../../configuration/pgdog.toml/databases.md) | [`min_pool_size`](../../../configuration/pgdog.toml/databases.md#min_pool_size) |
106+
| [`[[users]]`](../../../configuration/users.toml/users.md) | [`pool_size`](../../../configuration/users.toml/users.md#pool_size) |
107+
| [`[[users]]`](../../../configuration/users.toml/users.md) | [`min_pool_size`](../../../configuration/users.toml/users.md#min_pool_size) |
108+
109+
## Orchestrator integration
110+
111+
Autoscaling actions are performed entirely using the internal PgDog <-> control plane protocol and, therefore, will work with all orchestrators, including Kubernetes, ECS, and manual deployments.
112+
113+
### Kubernetes
114+
115+
If using autoscaling and deploying PgDog with our [Helm chart](../../../installation.md), make sure to set the pool-related settings to reflect the _total_ number of connections. For example, if deploying 3 replicas and the total pool size across the 3 pods is 600 connections, set it accordingly in `values.yaml`:
116+
117+
```yaml title="values.yaml"
118+
defaultPoolSize: 600
119+
replicas: 3
120+
121+
users:
122+
- name: "postgres"
123+
database: "prod"
124+
minPoolSize: 300 # 50% of the pool
125+
```
126+
127+
When PgDog pods are started, they will connect to the control plane and automatically adjust the pool settings to reflect the total number of pods in the deployment:
128+
129+
| Configuration | Value | Autoscaled value |
130+
|-|-|-|
131+
| `defaultPoolSize` | `600` | `200` |
132+
| `minPoolSize` | `300` | `100` |
133+
134+
!!! note "Automatic adjustment"
135+
The configuration adjustment happens inside the PgDog process. The control plane does not
136+
mutate the `ConfigMap` resource, so GitOps tools like ArgoCD will not detect this drift
137+
and continue to operate normally.

‎docs/enterprise_edition/control_plane/features/index.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
icon: material/format-list-bulleted-type
3+
---
4+
5+
# Features
6+
7+
The control plane provides operational features for monitoring, configuring, and managing PgDog deployments.
8+
9+
| Feature | Description |
10+
|-|-|
11+
| [Alerts](alerts.md) | Detect outliers in live PgDog metrics and send incidents to supported providers. |
12+
| [Autoscaling](autoscaling.md) | Automatically resize connection pools when PgDog nodes are added or removed. |
13+
| [Slack integration](slack.md) | Send deployment and configuration notifications to a Slack channel. |

‎docs/enterprise_edition/control_plane/features/slack.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
icon: material/slack
3+
---
4+
5+
# Slack integration
6+
7+
The control plane can send notifications to a Slack channel. Notifications include changes to managed PgDog deployments, like Helm chart updates, configuration reloading, and updates to database topology.
8+
9+
## Configuration
10+
11+
Slack integration is **disabled** by default and can be enabled with configuration:
12+
13+
```yaml title="values.yaml"
14+
control:
15+
config:
16+
slack:
17+
bot_token: "xoxb-[...]"
18+
channel: "C0123456789"
19+
```
20+
21+
The following parameters can be configured via the [Helm chart](../installation.md):
22+
23+
| Parameters | Description |
24+
|-|-|
25+
| `bot_token` | The Slack API bot token. |
26+
| `channel` | The Slack channel ID where the Slack bot is allowed to post messages. |
27+
28+
## Notifications
29+
30+
If Slack integration is configured, the control plane will send the following notifications to a Slack channel:
31+
32+
| Notification | Description |
33+
|-|-|
34+
| Helm install (start) | The control plane starts executing the `helm upgrade --install` command to modify/create a PgDog deployment. |
35+
| Helm install (end) | The control plane is finished executing the `helm upgrade --install` command. If any errors occur, they are included in the notification. |
36+
| Configuration reload | The control plane triggers a configuration reload on all PgDog instances in a deployment. |

‎docs/enterprise_edition/control_plane/index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,3 +73,10 @@ PgDog transmits the following information to the control plane:
7373
| Queries | Queries that are currently executing through each PgDog node. |
7474
| Query plans | Output of `EXPLAIN` for slow and sampled queries, collected in the background. |
7575
| Configuration | Current PgDog settings and database schema. |
76+
77+
## Read more
78+
79+
{{ next_steps_links([
80+
("Installation", "installation.md", "Deploy the control plane alongside your PgDog nodes and connect them together."),
81+
("Features", "features/index.md", "Explore control plane features like alerts, configuration management, instances, metrics, and Slack integration."),
82+
]) }}

‎docs/enterprise_edition/control_plane/installation.md‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ helm install control pgdogdev-ee/pgdog-control
1515

1616
The chart has a few external requirements, [documented below](#requirements).
1717

18-
## Guided install
18+
## Dependencies
1919

2020
While the chart creates and manages several resources, including an `Ingress`, some of them have external dependencies which cannot be created by Helm.
2121

@@ -31,9 +31,6 @@ The script requires that you have both the `awscli` and `kubectl` installed, whi
3131
!!! note "Read-only actions"
3232
The guided installation script is strictly **read-only** and will never make any modifications to your environment.
3333

34-
35-
## Requirements
36-
3734
Since the chart creates an `Ingress` resource for the web dashboard, an ingress controller is required to access the web dashboard. The chart supports four Ingress settings out of the box:
3835

3936
| Ingress | Description |
@@ -49,7 +46,7 @@ If deploying the dashboard with access to the Internet, make sure to configure a
4946

5047
## Ingress
5148

52-
Most of the settings that need to be provided are around the Ingress and OAuth authentication. The [guided install](#guided-install) will configure them automatically. However, if you're installing manually, they are documented below:
49+
Most of the settings that need to be provided are around the Ingress and OAuth authentication. The [guided install](#dependencies) will configure them automatically. However, if you're installing manually, they are documented below:
5350

5451
| Setting | Description | Example |
5552
|-|-|-|

‎docs/images/ee/alerts.png‎

35.5 KB
Loading

0 commit comments

Comments
 (0)