Skip to content

Commit 8d03a9e

Browse files
kaikailakaikaila
committed
pipelines: Add database configuration guide for KFP operation guide
Signed-off-by: Yunkai Li <yunli@redhat.com>
1 parent b035d40 commit 8d03a9e

2 files changed

Lines changed: 135 additions & 0 deletions

File tree

‎content/en/docs/components/pipelines/operator-guides/configure-database.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
+++
2+
title = "Database Configuration"
3+
description = ""
4+
weight = 4
5+
+++
6+
7+
{{% kfp-v2-keywords %}}
8+
9+
Kubeflow Pipelines (KFP) uses a relational database to store pipeline definitions, run history, and other metadata. The API server is the main component that interacts with the database.
10+
11+
By default, KFP deploys with MySQL. PostgreSQL is also available for a limited set of deployment configurations.
12+
13+
## MySQL (Default)
14+
15+
MySQL is the default database backend for KFP. It is automatically configured when you deploy KFP using the standard kustomize manifests. No additional database configuration is needed.
16+
17+
To deploy KFP with MySQL using the platform-agnostic overlay:
18+
19+
```bash
20+
export PIPELINE_VERSION={{% pipelines/latest-version %}}
21+
kubectl apply -k "github.com/kubeflow/pipelines/manifests/kustomize/cluster-scoped-resources?ref=$PIPELINE_VERSION"
22+
kubectl wait --for condition=established --timeout=60s crd/applications.app.k8s.io
23+
kubectl apply -k "github.com/kubeflow/pipelines/manifests/kustomize/env/platform-agnostic?ref=$PIPELINE_VERSION"
24+
```
25+
26+
For full installation instructions, see the [Installation](/docs/components/pipelines/operator-guides/installation/) guide.
27+
28+
MySQL is the fully supported backend, and it is the backend assumed by the deployment overlays for proxy-enabled, cache-disabled, pod-to-pod TLS, and artifact proxy configurations.
29+
30+
## PostgreSQL (Limited Support)
31+
32+
{{% alert title="Warning" color="warning" %}}
33+
PostgreSQL support is not yet part of a tagged Kubeflow Pipelines release. The instructions in this section apply to the `master` branch and are intended for development and evaluation, not for production. Production deployments should use MySQL until PostgreSQL support ships in a release.
34+
{{% /alert %}}
35+
36+
KFP can be deployed with PostgreSQL as its database backend using the `pgx` driver. Dedicated kustomize overlays are provided for this purpose:
37+
38+
- `manifests/kustomize/env/platform-agnostic-postgresql` — standalone (single-user)
39+
- `manifests/kustomize/env/platform-agnostic-multi-user-postgresql` — multi-user
40+
41+
### Support Scope
42+
43+
PostgreSQL support is deliberately scoped to the core deployment path. Only the following configuration is tested and supported:
44+
45+
- execution cache **enabled**
46+
- proxy **disabled**
47+
- pod-to-pod TLS **disabled**
48+
49+
No PostgreSQL overlay exists for the following combinations, so they are **not supported**:
50+
51+
| Mode | Unsupported combination |
52+
| --- | --- |
53+
| Standalone | PostgreSQL with pod-to-pod TLS enabled |
54+
| Standalone | PostgreSQL with the execution cache disabled |
55+
| Standalone | PostgreSQL with proxy enabled |
56+
| Multi-user | PostgreSQL with the execution cache disabled |
57+
| Multi-user | PostgreSQL with the artifact proxy enabled |
58+
59+
These combinations are also rejected explicitly by the project's CI deployment script, so they are not exercised in testing.
60+
61+
{{% alert title="Warning" color="warning" %}}
62+
**Pod-to-pod TLS is not available with PostgreSQL.** The only pod-to-pod TLS overlay, `platform-agnostic-standalone-tls`, is a standalone MySQL-based configuration, and there is no PostgreSQL equivalent for either standalone or multi-user deployments. Enabling pod-to-pod TLS on a PostgreSQL deployment does not encrypt traffic between pods.
63+
64+
Note that the absence of a multi-user TLS overlay is not specific to PostgreSQL: no multi-user pod-to-pod TLS overlay exists for any database backend. Switching to MySQL does not enable pod-to-pod TLS in multi-user mode.
65+
{{% /alert %}}
66+
67+
For proxy-enabled, cache-disabled, and artifact-proxy deployments, use the MySQL-backed configuration. Extending PostgreSQL support to these combinations is tracked in [kubeflow/pipelines#13822](https://github.com/kubeflow/pipelines/issues/13822).
68+
69+
### Deploying with PostgreSQL from `master`
70+
71+
Because PostgreSQL support is not yet in a tagged release, the released container images do not include it. Deploying the overlay at a release tag will not produce a working PostgreSQL deployment. You must use both the manifests and the container images built from `master`.
72+
73+
The overlays pin the API server and cache server images to the current release tag, so you need a small local overlay that references the remote manifests as a base and overrides those two images.
74+
75+
Create a directory and add a `kustomization.yaml`:
76+
77+
```yaml
78+
apiVersion: kustomize.config.k8s.io/v1beta1
79+
kind: Kustomization
80+
81+
resources:
82+
- github.com/kubeflow/pipelines/manifests/kustomize/env/platform-agnostic-postgresql?ref=master
83+
84+
images:
85+
- name: ghcr.io/kubeflow/kfp-api-server
86+
newTag: master
87+
- name: ghcr.io/kubeflow/kfp-cache-server
88+
newTag: master
89+
```
90+
91+
For a multi-user deployment, use the multi-user overlay as the base instead. Multi-user mode requires Istio; see the [multi-user guide](/docs/components/pipelines/operator-guides/multi-user/).
92+
93+
```yaml
94+
resources:
95+
- github.com/kubeflow/pipelines/manifests/kustomize/env/platform-agnostic-multi-user-postgresql?ref=master
96+
```
97+
98+
Then apply the cluster-scoped resources followed by your overlay:
99+
100+
```bash
101+
kubectl apply -k "github.com/kubeflow/pipelines/manifests/kustomize/cluster-scoped-resources?ref=master"
102+
kubectl wait --for condition=established --timeout=60s crd/applications.app.k8s.io
103+
kubectl apply -k .
104+
```
105+
106+
Note the following when using this path:
107+
108+
- The `resources` entry must be a remote URL or a relative path. Kustomize rejects absolute paths with a `new root ... cannot be absolute` error.
109+
- `kustomize edit set image` only modifies a local `kustomization.yaml`. It has no effect on a remote base, which is why the image overrides are declared in the file above.
110+
- `master` is a mutable tag. The images it points to change as commits land, so a redeployment may pick up different code.
111+
112+
### Deploying with PostgreSQL After Release
113+
114+
Once PostgreSQL support is included in a Kubeflow Pipelines release, the released images will include it and no image overrides are needed. Deploy the overlay directly:
115+
116+
```bash
117+
export PIPELINE_VERSION=<version-with-postgresql-support>
118+
kubectl apply -k "github.com/kubeflow/pipelines/manifests/kustomize/cluster-scoped-resources?ref=$PIPELINE_VERSION"
119+
kubectl wait --for condition=established --timeout=60s crd/applications.app.k8s.io
120+
kubectl apply -k "github.com/kubeflow/pipelines/manifests/kustomize/env/platform-agnostic-postgresql?ref=$PIPELINE_VERSION"
121+
```
122+
123+
For a multi-user deployment, use the `platform-agnostic-multi-user-postgresql` overlay instead:
124+
125+
```bash
126+
kubectl apply -k "github.com/kubeflow/pipelines/manifests/kustomize/env/platform-agnostic-multi-user-postgresql?ref=$PIPELINE_VERSION"
127+
```

‎content/en/docs/components/pipelines/operator-guides/installation/_index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,14 @@ Kubeflow Pipelines can be deployed with pod-to-pod TLS enabled. The API server s
5555

5656
Deploy KFP on a KinD cluster with pod-to-pod TLS enabled using the Makefile target [here](https://github.com/kubeflow/pipelines/blob/master/backend/Makefile). The corresponding manifests can be manually accessed [here](https://github.com/kubeflow/pipelines/tree/master/manifests/kustomize/env/cert-manager/platform-agnostic-standalone-tls).
5757

58+
## Deploying Kubeflow Pipelines with PostgreSQL
59+
60+
Kubeflow Pipelines uses MySQL as its database backend by default. It can alternatively be deployed with PostgreSQL, using the `pgx` driver, through the `platform-agnostic-postgresql` and `platform-agnostic-multi-user-postgresql` overlays.
61+
62+
PostgreSQL support is currently scoped to the core deployment path: execution cache enabled, proxy disabled, and pod-to-pod TLS disabled. No PostgreSQL overlay exists for proxy-enabled deployments, cache-disabled deployments, pod-to-pod TLS, or the multi-user artifact proxy. For those configurations, use the default MySQL-backed deployment.
63+
64+
For deployment instructions and the full support scope, see [Database Configuration](/docs/components/pipelines/operator-guides/configure-database/).
65+
5866
## Accessing the Kubeflow Pipelines UI
5967

6068
The Kubeflow Pipelines deployment requires approximately 3 minutes to complete.

0 commit comments

Comments
 (0)