You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/enterprise_edition/control_plane/index.md
+42-35Lines changed: 42 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,65 +4,72 @@ icon: material/console
4
4
5
5
# Control plane
6
6
7
-
Multi-node PgDog deployments require synchronization to perform certain tasks, like atomic configuration changes, toggling [maintenance mode](../../administration/maintenance_mode.md), [resharding](../../features/sharding/resharding/index.md), and more. To make this work, PgDog Enterprise comes with a control plane, an application deployed alongside PgDog, to provide coordination and collect and present system telemetry.
7
+
Multi-node PgDog deployments require synchronization to perform certain tasks, like atomic [configuration](../../configuration/index.md) changes, toggling [maintenance mode](../../administration/maintenance_mode.md) and [resharding](../../features/sharding/resharding/index.md).
8
8
9
-
## How it works
9
+
To make this work, PgDog Enterprise ships with a control plane: an application deployed alongside PgDog, which provides synchronization of administrative commands.
10
+
11
+
## Installation
12
+
13
+
Ready to deploy? See the [installation guide](installation.md).
10
14
11
-
The control plane and PgDog processes communicate via the network using HTTP. They exchange messages to send metrics, commands, and other metadata that allows PgDog to transmit real-time information to the control plane, and for the control plane to control the behavior of each PgDog process.
The control plane and PgDog processes communicate via the network using their own protocol, using HTTP(S) as the transport.
22
+
23
+
They exchange messages to send metrics, commands, and other metadata that allows PgDog to transmit real-time information to the control plane, and for the control plane to control the behavior of each PgDog process.
24
+
17
25
### Configuration
18
26
19
-
In order for PgDog to connect to the control plane, it needs to be configured with its endpoint address and an authentication token, both of which are specified in [`pgdog.toml`](../../configuration/pgdog.toml/general.md):
27
+
In order for PgDog to connect to the control plane, it needs to be configured with its endpoint address and an authentication token, both of which are set in [`pgdog.toml`](../../configuration/pgdog.toml/control.md):
The authentication token is generated by the control plane and identifies each PgDog deployment. PgDog nodes which are part of the same deployment should use the same token.
42
+
PgDog nodes that are part of the same deployment should use the same token. It can be any string value and serves to differentiate one PgDog deployment from another.
28
43
29
-
For example, if you're using our [Helm chart](../../installation.md#kubernetes), you can configure the endpoint and token in `values.yaml` as follows:
44
+
!!! info "Multiple PgDog deployments"
45
+
A control plane deployment is capable of managing several PgDog deployments. It's not necessary (although possible) to have one control plane per PgDog deployment.
The connection to the control plane is initiated by PgDog on startup and happens in the background. Upon connecting, PgDog will send its node identifier (randomly generated, or set in the `NODE_ID` environment variable) to register with the control plane, and start uploading telemetry and poll for commands.
PgDog initiates a connection to the control plane on startup. This happens in the background and doesn't block queries.
40
55
41
-
!!! note "Error handling"
42
-
Since most PgDog functions (including sharding) are configuration-driven, the control plane connection is **not required**
43
-
for PgDog to start and serve queries.
56
+
Upon connecting, PgDog will send its node identifier (set in the `NODE_ID` environment variable, or randomly generated) to register with the control plane, and will start uploading telemetry and poll for commands.
44
57
45
-
If any error is encountered while communicating with the control plane,
46
-
PgDog will continue operating normally, while attempting to reconnect periodically.
58
+
#### Error handling
47
59
60
+
Since most PgDog functions (including sharding) are configuration-driven, the control plane connection is **not required**
61
+
for PgDog to start or serve queries.
48
62
49
-
This architecture makes the communication link more resilient to unreliable network conditions.
63
+
If any error is encountered while communicating with the control plane,
64
+
PgDog will continue operating normally, while attempting to reconnect periodically.
50
65
51
66
### Telemetry
52
67
53
68
PgDog transmits the following information to the control plane:
54
69
55
70
| Telemetry | Description |
56
71
|-|-|
57
-
| [Metrics](../metrics.md) | The same [metrics](../../features/metrics.md) as exposed by the Prometheus endpoint (and the admin database), are transmitted at a much higher frequency, to allow for real-time monitoring. |
58
-
| [Active queries](../insights/active_queries.md) | Queries that are currently executing through each PgDog node. |
59
-
| [Query statistics](../insights/statistics.md) | Real-time statistics on each query executed through PgDog, like duration, idle-in-transaction time, and more. |
60
-
| [Errors](../insights/errors.md) | Recent errors encountered by clients, e.g. query syntax issues. |
61
-
| [Query plans](../insights/query_plans.md) | Output of `EXPLAIN` for slow and sampled queries, collected by PgDog in the background. |
72
+
| Metrics | System and utilization metrics, transmitted on a per-second frequency. |
73
+
| Queries | Queries that are currently executing through each PgDog node. |
74
+
| Query plans | Output of `EXPLAIN` for slow and sampled queries, collected in the background. |
62
75
| Configuration | Current PgDog settings and database schema. |
63
-
64
-
#### High availability
65
-
66
-
The control plane itself is backed by a PostgreSQL database, used for storing historical metrics, query statistics, configuration, and other metadata.
67
-
68
-
This allows multiple instances of the control plane to be deployed in a high-availability setup, since all actions are synchronized by PostgreSQL transactions and locks.
The chart has a few external requirements, [documented below](#requirements).
17
+
18
+
## Guided install
19
+
20
+
While the chart creates and manages several resources, including an `Ingress`, some of them have external dependencies which cannot be created by Helm.
21
+
22
+
If you're not sure if your Kubernetes cluster has all the necessary dependencies, we created a quick script you can run to validate this:
The script requires that you have both the `awscli` and `kubectl` installed, which it will use to inspect your environment.
30
+
31
+
!!! note "Read-only actions"
32
+
The guided installation script is strictly **read-only** and will never make any modifications to your environment.
33
+
34
+
35
+
## Requirements
36
+
37
+
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:
38
+
39
+
| Ingress | Description |
40
+
|-|-|
41
+
|[Nginx](#nginx)| Uses the `ingress-nginx` controller with `cert-manager` for TLS. The controller is widely used, although currently deprecated by the Kubernetes consortium. |
42
+
|[AWS ALB](#aws-alb)| Uses the AWS ELB controller to create a load balancer. Supports TLS termination with an ACM-managed certificate. |
43
+
| Gateway API | Uses the more modern Kubernetes [Gateway API](https://kubernetes.io/docs/concepts/services-networking/gateway/), with support for gateways like Envoy. |
44
+
| Custom | All labels and annotations are exposed to the chart caller, so you can configure your own Ingress. |
45
+
46
+
### Authentication
47
+
48
+
If deploying the dashboard with access to the Internet, make sure to configure authentication to protect against unauthorized access. The control plane supports OAuth2 and two providers: GitHub and Google.
49
+
50
+
## Ingress
51
+
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:
53
+
54
+
| Setting | Description | Example |
55
+
|-|-|-|
56
+
|`ingress.mode`| Which [ingress](#ingress) to use for the web dashboard. |`gateway`|
57
+
|`ingress.host`| DNS for the dashboard. Tightly coupled to the TLS certificate, if enabled. |`pgdog.acme.com`|
58
+
59
+
60
+
### Nginx
61
+
62
+
The [nginx ingress](https://github.com/kubernetes/ingress-nginx/) (deprecated, but still available) is supported out of the box, along with automatic TLS termination (using `cert-manager`).
63
+
64
+
| Setting | Description | Example |
65
+
|-|-|-|
66
+
|`ingress.nginx.clusterIssuer`| The name of the `ClusterIssuer` resource. |`letsencrypt-prod`|
67
+
68
+
##### Example
69
+
70
+
```yaml title="values.yaml"
71
+
ingress:
72
+
mode: nginx
73
+
host: pgdog.acme.com
74
+
nginx:
75
+
clusterIssuer: letsencrypt-prod
76
+
```
77
+
78
+
### AWS ALB
79
+
80
+
The [AWS ALB ingress](https://docs.aws.amazon.com/eks/latest/userguide/aws-load-balancer-controller.html) is supported out of the box and uses ACM for TLS termination at the load balancer.
81
+
82
+
| Setting | Description | Example |
83
+
|-|-|-|
84
+
| `ingress.aws.scheme` | `internet-facing` or `internal`. | `internet-facing` |
85
+
| `ingress.aws.certificateArn` | ARN of the ACM TLS certificate (validated externally, e.g., with DNS). | `arn:aws:acm:us-east-1:111111111111:certificate/abc-123` |
The client secret can be alternatively set as an environment variable:
128
+
129
+
| Provider | Variable |
130
+
|-|-|
131
+
| GitHub| `GITHUB_CLIENT_SECRET` |
132
+
| Google | `GOOGLE_CLIENT_SECRET` |
133
+
134
+
135
+
### Access control
136
+
`allowed_orgs`(GitHub) and `allowed_domains` (Google) restrict logins to members of those organizations or email domains. If left empty, anyone who can authenticate with the provider is allowed in.
137
+
138
+
Both accept a list, so you can allow more than one:
0 commit comments